writing-skills

Test-driven development for skill documentation follows the RED-GREEN-REFACTOR cycle: write failing tests first, implement the skill to pass those tests, then refactor. This ensures your skill behaves as intended before deployment and resists rationalization by agents.

Build rationalization tables that identify loopholes and spirit-vs-letter arguments, then close them through precise YAML frontmatter with name and description fields. Test edge cases with subagents under pressure scenarios to surface rationalization patterns early.

Use subagents to validate skills in pressure scenarios that expose failure modes. Run minimal, testable patterns through the RED-GREEN-REFACTOR cycle, then verify compliance against your rationalization table before rollout.

Skill YAML frontmatter requires at minimum a name field and description field. These support Claude Search Optimization through keyword coverage and token efficiency, improving discoverability while documenting the skill's exact scope.

Yes. Apply TDD to skill edits by writing tests for the changed behavior, verifying the edit passes those tests, and checking for new rationalization loopholes. This ensures edits don't degrade reliability or introduce unintended agent workarounds.

Untested skills lack clarity around edge cases and lack verification that agents follow intent rather than circumvent it through rationalization. TDD surfaces these gaps before deployment, ensuring the skill performs reliably in real usage.