| name | writing-skills |
| description | Use when creating new skills, editing existing skills, or verifying skills work before deployment |
Writing Skills
Overview
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.
TDD Mapping for Skills
| TDD Concept | Skill Creation |
|---|
| Test case | Pressure scenario with subagent |
| Production code | Skill document (SKILL.md) |
| Test fails (RED) | Agent violates rule without skill |
| Test passes (GREEN) | Agent complies with skill present |
| Refactor | Close loopholes while maintaining compliance |
SKILL.md Structure
Frontmatter (YAML):
- Two required fields:
name and description
name: Use letters, numbers, and hyphens onlydescription: Start with "Use when..." to focus on triggering conditions
Key Sections
- Overview with core principle
- When to Use / When NOT to Use
- Core Pattern with before/after comparisons
- Quick Reference table
- Common Mistakes with fixes
- Red Flags for self-checking
RED-GREEN-REFACTOR for Skills
RED: Run pressure scenario WITHOUT the skill - document exact behavior and rationalizations.
GREEN: Write minimal skill addressing those specific issues - re-test.
REFACTOR: Close loopholes as new rationalizations emerge.
The Iron Law
NO SKILL WITHOUT A FAILING TEST FIRST
