Sync Skills Across Multiple AI Agent Installations

Distributes a locally-authored skill across all 4 agent skill locations on a MacBook so every agent can discover it: Codex/OpenAI Agents at ~/.agents/skills/ (canonical - author here first), Claude Code at ~/.claude/skills/ (a symlink to ~/.agents/skills/, so it's auto-covered), Pi Agent at ~/.pi/agent/skills/ (also a symlink to ~/.agents/skills/, auto-covered - the path is nested under /agent/, not ~/.pi/skills/), and Hermes Agent at ~/.hermes/skills/ (an independent copy, the only location needing a manual copy).

Use it when a skill should be made available across multiple local agent skill folders, or when the user asks to sync or distribute skill updates to other agents. Do NOT use it for a project-specific skill - that belongs in ./.claude/skills/, ./.pi/agent/skills/, etc. inside the repo, not globally, since a project-local skill overrides the global one on collision. Also don't use it to edit just one agent's skill (e.g. a Hermes-only workflow) - patch that file directly instead of propagating it everywhere. Removing a skill globally is destructive: first show the exact skill directories that would be removed, confirm with the user, then use their preferred safe deletion method for ~/.agents/skills/ and ~/.hermes/skills/.

Author the skill in ~/.agents/skills/<skill-name>/SKILL.md first (the canonical location). Verify the .claude symlink is intact with a one-time check (ls -la ~/.claude/skills should show ~/.claude/skills -> ~/.agents/skills; if it's a real directory instead, the copies have diverged - ask before touching). Then copy only to .hermes, since .claude and .pi are symlinks already covered:

SKILL=<skill-name>
cp -r ~/.agents/skills/$SKILL ~/.hermes/skills/

Finally verify all 4 locations show identical byte counts for SKILL.md; if .claude or .pi shows a different count, that symlink is broken and needs investigating before proceeding. Updating an existing distributed skill uses the same flow - re-copy to .hermes/skills/ (the .claude and .pi symlinks update automatically) - but cp -r overwrites by default, so use rsync -a --delete instead if the skill folder has nested files that may have been removed:

rsync -a --delete ~/.agents/skills/$SKILL/ ~/.hermes/skills/$SKILL/

Covers four skill-loading agents and their known pitfalls: ~/.pi/skills/ is the wrong location for Pi (it loads only from ~/.pi/agent/skills/; anything found in the wrong path is an orphan, confirm with the user before deleting); ~/.claude/skills is a symlink, not a folder, so an explicit cp -r into it errors with "are identical" and should be skipped; project-local skill folders (./.pi/agent/skills/ or .pi/skills/ inside a repo) override the global one on collision and this skill only handles global distribution; .pi/agent/skills is a symlink to .agents/skills and shouldn't be cp'd into directly, while .hermes/skills remains the one independent copy that shouldn't be unilaterally consolidated into a symlink unless the user asks; a newly-distributed skill won't appear inside an already-running Hermes session until restart, since Hermes snapshots skills at session start, though it works immediately for future sessions and the other 3 agents; and SKILL.md filename casing matters on case-sensitive volumes, so it must stay uppercase.

Users running multiple local coding agents (Codex, Claude Code, Pi, Hermes) side by side who want one authored skill kept in sync across all of them, rather than maintaining four separate copies by hand.