write-a-skilllisted

# Writing Skills A skill exists to make a stochastic agent **predictable**: the same *process* every run, not the same output. Every lever below serves that. ## Process 1. **Gather requirements** - ask the user: - What task/domain does the skill cover? - What use cases (branches) should it handle? - Does it need executable scripts, or just instructions? - Any reference material to bundle? 2. **Decide invocation** (section 1) before drafting. 3. **Draft** - SKILL.md plus any bundled reference files or scripts. 4. **Review with user** - present the draft and ask: Does this cover your use cases? Anything missing or unclear? Should any section be more/less detailed? ## 0. Where it goes on disk **`.agents/skills/` is the source of truth. Never write a skill into `.claude/skills/` directly.** Three agents read these roots and only one reads `.claude`: Claude Code reads `~/.claude/skills`, while Codex, the ChatGPT app, and **Zed read only `~/.agents/skills`** (Zed's scan is flat, one level, and never looks at `.claude`). A skill authored into `.claude` alone is invisible to two of the three. | Kind | Create at | Then | |---|---|---| | Global, throwaway or machine-local | `~/.agents/skills/<name>/SKILL.md` | `ln -s ../../.agents/skills/<name> ~/.claude/skills/<name>` | | Global, kept in git (the usual case) | `~/dotfiles/.claude/skills/<name>/SKILL.md` | `bash ~/dotfiles/scripts/skills/link-dotfiles-skills.sh` (links into `~/.agents`, then mirrors to `~/.claude`) |