Distribute a Skill Across All Agents

A global skill must exist at all five locations on the user's Mac, directly or via symlink, for every agent to discover it.

Skill locations

• 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 in ~/.agents/skills/<skill-name>/SKILL.md, following effective-agent-skills.
2. Verify the Claude symlink (one-time check):

   ls -la ~/.claude/skills
   # Expect: ~/.claude/skills -> ~/.agents/skills
   

   If it is a real directory, copies have diverged, ask before touching.
3. Copy to Hermes; Claude and Pi are covered by symlinks:

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

4. Symlink into Cursor (skip if it already exists):

   [ -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:

   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 five numbers must match. If Claude, Pi, or Cursor differs, investigate the symlink before proceeding.

Update an existing skill