writing-skills

Test-driven development for skills uses a RED-GREEN-REFACTOR cycle: write a pressure scenario with subagents to establish baseline failure (RED), deploy the skill and verify compliance (GREEN), then refactor to close loopholes while maintaining compliance. This ensures documentation is clear and resistant to agent rationalization before deployment.

Rationalization resistance requires explicitly closing loopholes in skill guidance, addressing "spirit vs. letter" interpretations, and building rationalization tables that anticipate edge cases. The writing-skills Skill teaches how to construct frontmatter metadata and SKILL.md content that leaves no ambiguity for agents to exploit.

Claude Search Optimization (CSO) applies naming conventions using hyphens, writes descriptions in third person tied to triggering conditions, and selects keywords balancing specificity with search volume. The Skill provides guidelines for token-efficient frontmatter that maximizes discoverability while maintaining clarity.

Yes. The TDD workflow applies to creating, editing, and verifying CLAUDE skills. Test your edits with subagent pressure scenarios before deployment to confirm the skill still produces compliant behavior and hasn't introduced new rationalization vectors.

A SKILL.md requires frontmatter with name (hyphen-separated), description (third person, triggering conditions + what it does), and concise process documentation. The Skill provides exact frontmatter templates and RED-GREEN-REFACTOR guidance to build documentation that passes validation.

TDD surfaces how agents actually interpret guidance before deployment. Writing pressure scenarios first reveals compliance gaps and rationalization paths that forward documentation alone misses, letting you refactor toward genuine robustness rather than assumed clarity.