Use when creating new skills, editing existing skills, or verifying skills work before deployment
Writing skills IS Test-Driven Development applied to process documentation.
Core principle: If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
The Iron Law: No skill without a failing test first. Same as TDD — no exceptions.
A skill is a reference guide for proven techniques, patterns, or workflows. Skills help future AI instances find and apply effective approaches.
Skills are: Reusable techniques, patterns, tools, reference guides
Skills are NOT: Narratives about how you solved a problem once
| TDD Concept | Skill Creation |
|---|---|
| Test case | Pressure scenario (test WITHOUT skill) |
| Production code |
| Skill document (SKILL.md) |
| RED | Agent violates rule without skill (baseline) |
| GREEN | Agent complies with skill present |
| Refactor | Close loopholes while maintaining compliance |
Follow RED-GREEN-REFACTOR. Write baseline scenario BEFORE writing the skill.
Frontmatter (YAML):
name and descriptionname: letters, numbers, hyphens onlydescription: "Use when..." — triggering conditions ONLY, never workflow summary---