Write and refine agent skills. Use when generating skills from docs, extracting from sessions, designing tool interfaces, managing lifecycle, or writing for dual-harness patterns.
TDD for agent instructions. Test, write, shorten.
Use the right reference file for your task:
Note: Skill reference files must be resilient to context compaction. If an agent summarizes this routing table, ensure the distinct purpose of each file remains clear.
Create a skill when:
Don't create skills for one-off solutions, standard practices, or constraints enforceable with automation.
Only instructions that change agent behavior in ways the codebase can't convey on its own.
| Keep | Cut |
|---|---|
Specific tooling (use uv, run shellcheck) | Motivational framing |
| Concrete constraints (paths, commands) | Rationalization tables |
| Checklists and decision tables | Narrative examples |
| Error messages and stop conditions | Mandatory gates |
| Cross-references to other skills | Overviews and directory listings |
The description is the activation trigger. Include WHAT and WHEN. Describe triggering conditions only — not the skill's workflow.
# Good — triggering conditions