Publish skills through the agent-neutral skill home

user/README.md

@@ -13,7 +13,7 @@ and one file says where each piece goes.
 | Path | Goes to | Why |
 | --- | --- | --- |
 | `agents/AGENTS.md` | `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md` | Two tools, two names, one file. These were byte-identical copies before this, waiting to disagree. |
-| `agents/skills/` | `~/.agents/skills`, `~/.claude/skills` | A skill installed on any machine lands in the checkout. The Claude path is `linkdir` — see below. |
+| `agents/skills/` | `~/.agents/skills`, `~/.claude/skills` | Personal skills live once in the checkout. Both destinations use `linkdir` so Panama's shipped skills can live beside them. |
 | `agents/rules/` | `~/.claude/rules` | |
 | `ssh/config` | `~/.ssh/config` | Host aliases only. Keys are per-machine and are never tracked. |
 | `espanso/identity.yml` | `~/.config/espanso/match/identity.yml` | Copied, not linked, because a machine may add its own triggers. |
@@ -27,22 +27,22 @@ destination is empty. `linkdir` is the third, and it exists because one
 destination is no longer only ours.
 
 Panama ships its own agent skills now (`skills/`, linked by
-`setup/scripts/link-skills`), and they go to `~/.claude/skills` — the same
-directory the personal ones went to as a single symlink. A directory cannot be
-a symlink to two places, so that entry became `linkdir`: the destination is a
-real directory, and each child of `user/agents/skills/` is linked into it
-individually. `~/.agents/skills` is still a whole-directory `link`, because
-nothing else claims it.
+`setup/scripts/link-skills`), and they go to both skill homes. A directory
+cannot be a symlink to two places, so both personal entries use `linkdir`: each
+destination is a real directory, and each child of `user/agents/skills/` is
+linked into it individually.
 
 Two consequences, recorded rather than fixed:
 
 - **A personal skill named like a shipped one shadows it.** `link-user` runs
-  after `link-skills` and displaces what it finds, so the personal one wins.
-  That is the intent, and it is the precedence Claude Code uses anyway.
+  after `link-skills` and displaces what it finds, so the personal one wins in
+  both skill homes.
 - **A new personal skill needs a re-link to appear.** The whole-directory link
   showed a newly created skill instantly; per-child links do not know about a
-  child that did not exist when they were made. Run `panama update` or
-  `setup/scripts/link-user` after adding one.
+  child that did not exist when they were made. Put new shared skills in
+  `user/agents/skills/`, then run `panama update` or `setup/scripts/link-user`.
+  A tool that installs directly into a home skill directory creates a
+  machine-local skill until it is moved into the checkout.
 
 ## It is off unless you say yes
 

user/agents/skills/writing-for-agents/SKILL-MECHANICS.md

@@ -16,7 +16,9 @@ ln -s ../../.agents/skills/<name> ~/.claude/skills/<name>
 Writing a second copy into `~/.claude/skills/` gives you two files that drift, and the drift is
 silent because each harness only ever reads its own. One home, one symlink per harness that needs it.
 
-A skill that only makes sense inside one repo belongs in that repo, at `<repo>/.claude/skills/`.
+A skill that only makes sense inside one repo lives once at
+`<repo>/.agents/skills/<name>/`. Point Claude Code at that source with a
+`<repo>/.claude/skills/<name>` symlink.
 
 ## Frontmatter
 

user/manifest

@@ -28,14 +28,13 @@
 link  agents/AGENTS.md   ~/.claude/CLAUDE.md
 link  agents/AGENTS.md   ~/.codex/AGENTS.md
 
-# Skills, at both paths that look for them. Linked so that a skill installed by
-# any tool lands in the checkout and `panama update` offers to commit it.
+# Skills, at both paths that look for them. Each tracked skill is linked from
+# this checkout so edits stay shared and `panama update` offers to commit them.
 #
-# ~/.agents/skills is this directory and nothing else, so it stays one link.
-# ~/.claude/skills also holds the skills Panama itself ships, put there by the
-# link-skills stage, so it is a real directory with one link per skill -- and
-# this stage runs after that one, so a personal skill wins a name collision.
-link     agents/skills   ~/.agents/skills
+# Both destinations also hold skills Panama itself ships, put there by the
+# link-skills stage, so both are real directories with one link per skill. This
+# stage runs after that one, so a personal skill wins a name collision.
+linkdir  agents/skills   ~/.agents/skills
 linkdir  agents/skills   ~/.claude/skills
 
 link  agents/rules       ~/.claude/rules