Write Skill

Writing for agents is test-first development applied to prose. The same loop ships every document an agent reads: skills, AGENTS.md, CLAUDE.md, system prompts.

1. Baseline first: run the scenario the document targets on an agent WITHOUT it, and record exactly how it fails or rationalizes. No observed failure means the document has nothing to teach.
2. Write the minimum prose that fixes those specific failures. Not a manual: the shortest process that changes the behavior.
3. Re-run the scenario with the document loaded. It passes or the document is wrong.
4. Close loopholes: new rationalizations found on re-runs get plugged, then verified again.

A test harness changes mechanics, not the loop: when one exists, automate the baseline re-run.

Conventions for skills in this repo:

• Frontmatter carries name (letters, digits, hyphens) and description. The description states when to fire, with trigger phrasing ("Use when..."), not a summary of the process.
• disable-model-invocation: true only for skills that must never fire on their own; the description then reads as a human-facing one-liner.
• Keep SKILL.md lean. Separate files only for heavy reference or reusable assets; link them relatively.
• Name the capability, not the tool. A harness binding (a subagent, the question tool, /design, run) is written as a preference, with what to do when it is absent. Degrade the mechanism, never the guarantee: where no substitute exists, the skill stops and says so rather than proceeding without it.
• No em dashes. Decisive present tense. Zero upstream or status mentions.

Skip it when the work is a one-off, when standard practice is already well documented, or when a linter or hook could enforce the rule mechanically.