SKILL.md

Writing Skills

Writing a skill is test-driven development applied to documentation. The test case is a pressure scenario run by a fresh agent; RED is watching it fail without the skill; GREEN is compliance with the skill loaded; REFACTOR is closing the loopholes it found. If you never watched an agent fail without the skill, you do not know the skill teaches anything.

The iron law

No skill without a failing test first. This covers new skills AND edits. Run the baseline scenario before writing, document the exact rationalizations the agent used, write the skill against those specific failures, verify compliance, then hunt new rationalizations and plug them. Wrote the skill first? Delete it and start with the baseline. "Just adding a section" is an edit and follows the same law.

Read references/testing-and-hardening.md when creating or refactoring a skill: it carries the TDD mapping, pressure-scenario design, and the anti-pattern list.

What is a skill

A reusable reference for a proven technique, pattern, or tool. Not a narrative about how you solved something once.

Create one when the technique was not intuitively obvious, you would reference it again across projects, and others would benefit. Do not create one for one-off solutions, standard well-documented practice, project-specific conventions (put those in the project's instructions file), or anything enforceable with a regex or validator (automate it instead; save documentation for judgment calls).

Structure

skills/
  skill-name/
    SKILL.md          # required
    references/*.md   # heavy reference only (100+ lines)
    scripts, tools    # reusable code only

Keep principles, patterns, and short code inline. Split out only heavy reference and reusable tools. Name skills verb-first by the action or insight: condition-based-waiting beats async-test-helpers; gerunds work for processes.

The description field

The description is how future agents find and choose the skill. Two rules:

Triggers only, never workflow. Testing shows agents follow a workflow summarized in the description instead of reading the body. A description saying "with code review between tasks" produced one review where the body required two. State when to load the skill; let the body say what to do.
Concrete and searchable. Symptoms, situations, error messages, tool names. Third person, under 500 characters. Describe the problem ("tests pass inconsistently"), not one technology's symptom, unless the skill is technology-specific.

Token economy

Every frequently-loaded skill taxes every conversation. Targets: frequently-loaded skills under 200 words, others under 500. Techniques: point to --help output instead of documenting flags; cross-reference other skills by name instead of repeating their content; one excellent example instead of five mediocre ones in five languages; compress dialogue examples to their skeleton. Never use force-loading link syntax that inlines a whole file where a name suffices.

Good vs bad

Bad description: description: For TDD. Write test first, watch it fail, write minimal code, refactor. It summarizes the workflow (agents will follow it and skip the body) and gives no trigger.

Good description: description: Use when implementing any feature or bugfix, before writing implementation code. Pure trigger. The body owns the process.

Verification

Run the pressure scenario against a fresh agent twice: once without the skill, once with it loaded. Expect: the baseline run violates the rule and the loaded run complies, citing the skill. If the baseline already complies, the skill documents the obvious; do not ship it. If the loaded run still violates, capture the new rationalization verbatim, patch the skill, and re-run until it holds.

Completion checklist

[ ] Baseline scenario run BEFORE writing; failures documented verbatim
[ ] Skill addresses those specific failures, not hypothetical ones
[ ] Compliance verified with the skill loaded; loopholes closed and re-verified
[ ] Description states triggers only, no workflow summary, under 500 chars
[ ] Word budget met; heavy material split into references/
[ ] Name is verb-first and searchable; cross-references by skill name only

Any box unchecked: not done. Fix or say so.

Footguns

Testing with yourself. You wrote the skill; you cannot un-know it. Baselines and compliance runs need fresh agent instances with no authorship context.
Descriptions that summarize. The single highest-impact defect. It turns the skill body into documentation nobody reads.
Narrative skills. "How I fixed the deploy bug" helps nobody. Extract the reusable technique or write nothing.
Soft edits. Editing a hardened skill without re-running its scenarios quietly reopens closed loopholes. Edits are code changes; they need the test.

Red flags

"It's a simple addition, no test needed"
"I'll test it after I write it"
"The skill is obviously correct"
"This edit is just documentation"
"I ran it in my head"

Same discipline as code TDD, same closure: an untested skill or edit is unverified process documentation, and rephrasing the excuse does not verify it. Baseline first, always.

writing-skills