Writing Skills

Why a skill exists

A skill wrangles determinism out of a stochastic system. The root virtue is predictability: the agent takes the same process on every run — not that it emits identical output. A brainstorming skill should reliably diverge; its tokens vary, its behavior doesn't. Every rule in this document is a lever on predictability.

The Iron Law

NO NEW SKILL AND NO EDIT TO A SKILL SHIPS WITHOUT A FAILING TEST FIRST

Writing skills is test-driven development applied to process documentation. The cycle:

1. RED — watch it fail. Run the scenario WITHOUT the skill (for an edit: with the current version). Record the exact failures and rationalizations verbatim — they define what the text must prevent. If the baseline agent does NOT fail, stop: there is nothing to fix, and text with no failure behind it is a no-op.
2. GREEN — minimal text. Write the smallest skill text that addresses those recorded failures — nothing for hypothetical ones. Re-run the same scenario with the skill. Compliance, or the text is unclear: revise and re-run.
3. REFACTOR — close loopholes. Under pressure the agent will invent new rationalizations. Capture each verbatim, add an explicit counter, re-test. Repeat until the skill holds under maximum pressure.

Wrote the text before running the baseline? You documented what you guess agents do wrong, not what they do wrong. Run the baseline now, before keeping a word of it.