writing-skills

Test-driven development for skills ensures bulletproof documentation by writing tests first, running pressure scenarios with subagents to expose failures, then iterating with explicit loophole closures. This RED-GREEN-REFACTOR loop catches rationalizations before deployment.

Create realistic pressure scenarios and run them with subagents to observe how they handle edge cases and ambiguity. Document failures, then refactor your skill's frontmatter and language to close gaps, repeating until compliance holds.

Use SKILL.md frontmatter with explicit name and description, keep YAML frontmatter within limits, and write test-first documentation that maps requirements to observable agent behavior. Iterate when tests fail to close loopholes.

TDD applies to creating, editing, or validating skills across Claude/Codex environments. Whether you're drafting new skills or refining existing ones, pressure-test them with subagents and refactor until they pass compliance scenarios.

Writing is drafting; reliability requires testing. This skill enforces iterative failure observation—running subagents through scenarios to spot where agents rationalize away your intent, then refactoring language and constraints to eliminate those gaps.

Apply CSO (Claude Search Optimization) principles: craft clear, discoverable descriptions in your skill frontmatter that match how users search. Pair this with TDD validation to ensure your optimized wording actually guides reliable agent behavior.