write-a-skill

# Writing Skills ## Process 1. **Gather requirements** - ask user about: - What task/domain does the skill cover? - What specific use cases should it handle? - Does it need executable scripts or just instructions? - Any reference materials to include? 2. **Draft the skill** - create: - SKILL.md with concise instructions - Additional reference files if content exceeds 500 lines - Utility scripts if deterministic operations needed 3. **Review with user** - present draft and ask: - Does this cover your use cases? - Anything missing or unclear? - Should any section be more/less detailed? ## Skill Structure ``` skill-name/ ├── SKILL.md # Main instructions (required) ├── REFERENCE.md # Detailed docs (if needed) ├── EXAMPLES.md # Usage examples (if needed) └── scripts/ # Utility scripts (if needed) └── helper.js ``` ## SKILL.md Template ```md --- name: skill-name description: Brief description of capability. Use when [specific triggers]. --- # Skill Name ## Quick start [Minimal working example] ## Workflows [Step-by-step processes with checklists for complex tasks] ## Advanced features [Link to separate files: See [REFERENCE.md](REFERENCE.md)] ``` ## Description Requirements The description is **the only thing your agent sees** when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill ba...