writing-skills

Test-driven development for skills uses a RED-GREEN-REFACTOR cycle: first test the skill's behavior with subagents without it to identify gaps, then write the skill to address those failures, and iterate to close loopholes. This ensures agents consistently discover and comply with the skill under real-world pressure.

Create realistic pressure scenarios combining time constraints, sunk cost, and authority pressures, then use subagents to simulate actual usage. This reveals whether agents rationalize away the skill or comply consistently, exposing weaknesses before deployment.

Claude Search Optimization (CSO) guidelines cover rich descriptions, comprehensive keyword coverage, and token efficiency. Apply these during skill documentation to ensure the skill appears in relevant searches and loads without unnecessary overhead.

Use concise frontmatter paired with structured SKILL.md and explicit validation workflows. This combination delivers clarity about what the skill does, when to use it, and how to verify it works correctly across agent-specific directories.

The test-driven approach applies to creation, editing, and verification of skills. Apply it during red-green-refactor cycles whenever you modify a skill to ensure changes close behavioral gaps and maintain compliance.