Writing Skills

Gotchas

Generic description — "Helps with X" gives the agent no way to distinguish this skill. Always include a concrete Use when [specific triggers] clause with keywords the agent will see in real requests.
Missing trigger keywords — if the description omits the words users naturally say ("triage", "handover", "cleanup"), the skill never loads. Test: would the description match the user's message verbatim?
Over-stuffed SKILL.md — dumping all edge cases into SKILL.md causes the agent to pursue unproductive paths. Move rarely-needed content to references/ and add a conditional load instruction ("read references/X.md if Y").
No working example — a template or inline snippet is more reliable than prose description. If the output has a fixed structure, show it.
Stale harness references — skills that read setup config (issue tracker, labels, board) must include "run /setup-harness-skills if missing context" or they silently fail on unconfigured projects.

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?