feat(update-skills): dual install target — ~/.claude/skills + ~/.agents/skills (agent-neutral); pi settings hack removed (v0.2.1)

skills/update-skills/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: update-skills
 author: ours
-version: 0.2.0
+version: 0.2.1
 description: >
   Full uplift cycle for an existing skills installation: git pull,
   conditionally rebuild MCP servers, install skills, show version diff, suggest
@@ -54,6 +54,10 @@ If no MCP changes:
 
 > Skills updated. Start a new session (or `/clear`) for changes to take full effect.
 
+Both agents pick up the new catalog on their next session: Claude Code reads
+`~/.claude/skills` natively; pi reads `~/.agents/skills` natively (default
+scan path — no settings needed). See "Install targets" below.
+
 ### 4. Offer to run new setup skills
 
 If the script detected new `setup-*` skills that aren't yet installed:
@@ -62,6 +66,20 @@ If the script detected new `setup-*` skills that aren't yet installed:
 
 The user decides — never auto-run setup skills.
 
+## Install targets (dual, agent-neutral)
+
+The canon is the git repo — `skills/<name>/SKILL.md`. `install.sh` / `install.ps1`
+install into **both** agent dirs (identical copies, synced by the script — no drift):
+
+| Target | Agent | Why |
+|---|---|---|
+| `~/.claude/skills` | Claude Code | Claude Code reads this natively; custom skill dirs are NOT configurable in Claude Code (only plugin `skillsPaths`) |
+| `~/.agents/skills` | pi | pi reads this natively (default scan path); the agent-neutral `.agents/` namespace is our convention |
+
+`$CLAUDE_SKILLS_DIR` / `$env:CLAUDE_SKILLS_DIR` overrides only the claude target (for testing/CI).
+pi must NOT have `~/.claude/skills` in its settings `skills` array — that was the old vendor-locked
+setup; pi loads `~/.agents/skills` by default. Verify with `pi --help` / a fresh session listing skills.
+
 ## What the scripts do
 
 The update scripts (`scripts/update.sh` and `scripts/update.ps1`) handle:
@@ -76,7 +94,7 @@ The update scripts (`scripts/update.sh` and `scripts/update.ps1`) handle:
 ## Out of scope
 
 - **Greenfield bootstrap** — use `project-bootstrap` for first-time setup on a new machine.
-- **`--prune` flag** — removing skills not in `skills/` from `~/.claude/skills/`. Tracked separately in `[install-ps1]`.
+- **`--prune` flag** — removing skills not in `skills/` from the install targets (both `~/.claude/skills/` and `~/.agents/skills/`). Tracked separately in `[install-ps1]`.
 - **Hermes-side update** — `hermes-installer-skill` handles the Hermes/Linux factory path.
 - **Auto-run setup skills** — the user decides which new setup skills to configure.