distribute-skill-to-all-agents · diff

git:20260914.5a369a8 to git:20260925.cb72780

31 added, 28 removed. Audit A to A.

---
name: distribute-skill-to-all-agents
- description: Distribute a skill across the 4 agent skill folders (Codex, Claude Code, Pi, Hermes) so all agents see it. Use when the user says "distribute this skill", "sync skills across agents", or after creating/updating a skill that should be global. Covers the symlink layout and the ~/.pi/agent/skills trap.
+ description: Distribute global skills across Codex, Claude Code, Pi, Hermes, and Cursor. Use for "distribute this skill", "sync skills across agents", or after creating or updating a global skill.
---
# Distribute a Skill Across All Agents
- The user has 4 agent skill locations on their MacBook. A skill must exist in each (or via symlink) to be discoverable by every agent.
+ A global skill must exist at all five locations on the user's machine, directly or via symlink, for every agent to discover it.
- ## The 4 Canonical Locations
+ ## Skill locations
- | Agent | Skills Folder | Notes |
- |---|---|---|
- | Codex / OpenAI Agents | `~/.agents/skills/` | **Canonical** — author skills here first |
- | Claude Code | `~/.claude/skills/` | **Symlink → `~/.agents/skills/`** — writing to `.agents/skills` automatically covers Claude |
- | Pi Agent | `~/.pi/agent/skills/` | **Symlink → `~/.agents/skills/`** — auto-covered. (Path is `/agent/` nested — NOT `~/.pi/skills/`) |
- | Hermes Agent | `~/.hermes/skills/` | Independent copy — the only one needing a manual copy |
+ - **Codex / OpenAI Agents:** `~/.agents/skills/` is canonical. Author skills here first.
+ - **Claude Code:** `~/.claude/skills/` → `~/.agents/skills/`; covered automatically.
+ - **Pi Agent:** `~/.pi/agent/skills/` → `~/.agents/skills/`; covered automatically. The nested `/agent/` is required, not `~/.pi/skills/`.
+ - **Hermes Agent:** `~/.hermes/skills/` is an independent copy; only Hermes needs copying.
+ - **Cursor (IDE + CLI):** `~/.cursor/skills/` is a real folder that does not reliably read `~/.agents/skills/`. Add one symlink per skill. Never use `~/.cursor/skills-cursor/`; it holds Cursor's built-ins.
## Workflow
- 1. **Author the skill in `~/.agents/skills/<skill-name>/SKILL.md`** (canonical). Follow `effective-agent-skills` SKILL.md guidance.
- 2. **Verify the `.claude` symlink is intact** (one-time check):
+ 1. **Author in `~/.agents/skills/<skill-name>/SKILL.md`**, following `effective-agent-skills`.
+ 2. **Verify the Claude symlink** (one-time check):
```bash
ls -la ~/.claude/skills
# Expect: ~/.claude/skills -> ~/.agents/skills
```
- If it's a real directory instead of a symlink, the user has diverged copies — ask before touching.
- 3. **Copy to `.hermes` only** (`.claude` and `.pi` are symlinks — already covered):
+ If it is a real directory, copies have diverged — ask before touching.
+ 3. **Copy to Hermes**; Claude and Pi are covered by symlinks:
```bash
SKILL=<skill-name>
cp -r ~/.agents/skills/$SKILL ~/.hermes/skills/
```
- 4. **Verify all 4 locations** show identical byte counts:
+ 4. **Symlink into Cursor** (skip if it already exists):
```bash
- for p in ~/.agents/skills/$SKILL ~/.claude/skills/$SKILL ~/.pi/agent/skills/$SKILL ~/.hermes/skills/$SKILL; do
+ [ -e ~/.cursor/skills/$SKILL ] || ln -s ~/.agents/skills/$SKILL ~/.cursor/skills/$SKILL
+ ```
+ If a real Cursor copy exists and differs, compare versions and ask before replacing.
+ 5. **Verify matching byte counts at all five locations**:
+ ```bash
+ for p in ~/.agents/skills/$SKILL ~/.claude/skills/$SKILL ~/.pi/agent/skills/$SKILL ~/.hermes/skills/$SKILL ~/.cursor/skills/$SKILL; do
echo "$p: $(wc -c < $p/SKILL.md) bytes"
done
```
- All four numbers must match. If `.claude` or `.pi` shows a different byte count, that symlink is broken — investigate before proceeding.
+ All five numbers must match. If Claude, Pi, or Cursor differs, investigate the symlink before proceeding.
- ## Updating an Existing Distributed Skill
+ ## Update an existing skill
- Same flow — re-copy from `~/.agents/skills/` to `.hermes/skills/`. The `.claude` and `.pi` symlinks update automatically. `cp -r` overwrites by default; use `rsync -a --delete` if the skill folder has nested files that may have been removed:
+ Re-copy from `~/.agents/skills/` to `~/.hermes/skills/`; Claude, Pi, and symlinked Cursor skills update automatically. `cp -r` overwrites by default. Use `rsync -a --delete` when nested files may have been removed:
```bash
rsync -a --delete ~/.agents/skills/$SKILL/ ~/.hermes/skills/$SKILL/
```
## Pitfalls
- - **`~/.pi/skills/` is the wrong location.** Pi Agent loads from `~/.pi/agent/skills/` only. A skill placed in `~/.pi/skills/` is invisible. If you find skills already there, they're orphans — confirm with the user before deleting.
- - **`~/.claude/skills` is a symlink, not a folder.** `cp -r ~/.agents/skills/foo ~/.claude/skills/` will error with "are identical". Skip the explicit Claude copy.
- - **Project-local skills exist too** — `./.pi/agent/skills/` (or `.pi/skills/`) inside a repo overrides the global one on collision (later-discovered wins). This skill only handles GLOBAL distribution.
- - **`.pi/agent/skills` is a symlink → `.agents/skills`.** Don't `cp` into it (errors "are identical"); it auto-syncs. Only `.hermes/skills` is an independent copy — don't unilaterally consolidate Hermes into a symlink unless the user asks.
- - **Hermes snapshots skills at session start.** A newly-distributed skill won't appear inside a running Hermes session until restart (it works fine for future sessions and for the other 3 agents immediately).
- - **Filename casing matters on case-sensitive volumes.** `SKILL.md` must be uppercase.
+ - **`~/.pi/skills/` is the wrong global location.** Pi loads from `~/.pi/agent/skills/`; skills in the former are invisible orphans. Confirm with the user before deleting them.
+ - **Do not copy into the Claude or Pi symlinks.** They already point to `~/.agents/skills/`; copying there errors with "are identical". Only Hermes is independent. Do not replace it with a symlink unless the user asks.
+ - **Project-local skills can override global skills** on collision (later-discovered wins), including `./.pi/agent/skills/` or `.pi/skills/` inside a repo. This workflow handles only global distribution.
+ - **Hermes and Cursor load skills at session start.** Restart running sessions to discover a newly distributed skill.
+ - **Filename casing matters** on case-sensitive volumes: use uppercase `SKILL.md`.
- ## When NOT to Use This Skill
+ ## When not to use this skill
- - Skill is project-specific → put it in `./.claude/skills/`, `./.pi/agent/skills/`, etc. inside the repo, not globally.
- - Editing one agent's skill only (e.g. a Hermes-only workflow) → patch that file directly, don't propagate.
- - Removing a skill globally → `rm -rf` from `~/.agents/skills/` (covers `.claude` + `.pi` symlinks) and from `~/.hermes/skills/` (and confirm with the user first; deletion is destructive).
+ - **Project-specific skill:** use repo-local `./.claude/skills/`, `./.pi/agent/skills/`, etc.
+ - **Single-agent edit** (e.g. Hermes-only): patch that file directly without propagating.
+ - **Global removal:** confirm with the user first; deletion is destructive. Remove with `rm -rf` from `~/.agents/skills/` (covers Claude and Pi) `~/.hermes/skills/`, and the `~/.cursor/skills/` symlink.