domains / agent-tooling / distribute-global-skill / distribute-skill-to-all-agents

distribute-skill-to-all-agents

Skill card

combined

The sickn33 copy is a mirror of the davidondrej procedure but it explicitly drops Cursor from the canonical set (4 locations vs 5), while the davidondrej copy adds Cursor-specific steps (per-skill symlink, never use skills-cursor, byte-count check across 5 paths). Crowning one would hide a real alternative: the davidondrej version is the more complete procedure, but the sickn33 version is a valid 4-agent variant for users without Cursor. The combined instruction preserves the 5-location workflow and flags the 4-vs-5 disagreement.

Repositories

Other copies

Combined skill

---
name: distribute-skill-to-all-agents
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

A global skill must exist at all configured agent 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):
   ```bash
   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:
   ```bash
   SKILL=<skill-name>
   cp -r ~/.agents/skills/$SKILL ~/.hermes/skills/
   ```
4. **Symlink into Cursor** (skip if it already exists):
   ```bash
   [ -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 configured 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 numbers must match. If Claude, Pi, or Cursor differs, investigate the symlink before proceeding.

## Update an existing skill

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

- **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 from `~/.agents/skills/` (covers Claude and Pi), `~/.hermes/skills/`, and the `~/.cursor/skills/` symlink.

## Conflicts

- **davidondrej/skills** includes Cursor as a fifth canonical location with a per-skill symlink step and a 5-location byte-count verification; **sickn33/agentic-awesome-skills** omits Cursor and verifies only 4 locations. If the user does not use Cursor, skip step 4 and the Cursor entry in the verification loop.
- **davidondrej/skills** states that both Hermes and Cursor load skills at session start; **sickn33/agentic-awesome-skills** states only Hermes snapshots at session start. Restart both if Cursor is in use.
- **davidondrej/skills** provides an explicit `rm -rf` removal sequence; **sickn33/agentic-awesome-skills** requires showing the exact directories, confirming with the user, and using the user's preferred safe deletion method. Prefer the confirm-first approach for destructive removals.