make-skill

Start by running pressure scenarios with subagents without any skill to document baseline failures verbatim. Then write a SKILL.md file with name and description frontmatter that addresses only those observed failures, and re-test until agents comply under pressure.

TDD for skills applies the RED-GREEN-REFACTOR cycle to documentation: run scenarios without the skill to watch agents fail, write minimal skill content addressing those failures, then refactor to close loopholes agents discover. No skill should exist without a failing baseline test first.

The description must state both what the skill does and when to use it, written in third person with a maximum of 1024 characters. Include concrete triggers, symptoms, and searchable keywords so agents can discover it from system prompt metadata.

Run pressure scenarios combining three or more pressures like time constraints, sunk cost, and exhaustion with subagents. Document exact rationalizations verbatim, then verify the skill prevents those specific violations and iterate until no new loopholes appear.

Skip skill creation for one-off solutions, practices already well-documented elsewhere, project-specific conventions that belong in CLAUDE.md or AGENTS.md, and mechanical constraints that can be enforced with regex or validation scripts instead of documentation.

Agents rationalize violations using excuses like sunk cost, pragmatism, or spirit-versus-letter arguments when facing time pressure or exhaustion. Skills must name every observed loophole explicitly and state that violating the letter of the rules violates the spirit.