write-harness-skilllisted

# 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. --- ## 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** - work