writing-skills

Test-driven development for documentation applies a RED-GREEN-REFACTOR workflow to catch rationalizations and close loopholes. You observe baseline agent failures, draft a minimal skill to address them, then retest for full compliance.

To stop rationalizations, you capture baseline failure scenarios where the agent deviates from intent, then iterate on the documentation to close those specific loopholes. This structured baselining ensures bulletproof compliance.

Creating a SKILL.md with progressive disclosure involves structuring concise, discoverable entries that define trigger contexts and usage conditions. This makes the skill easy to load in Claude without overwhelming the context window.

Yes, YAML frontmatter is required to define when to use the skill and the contexts in which it should trigger. This structured metadata ensures the agent loads the correct instructions at the appropriate time.

The RED-GREEN-REFACTOR workflow applies to documentation quality assurance by first capturing baseline failures, drafting minimal guidance to make tests pass, then refactoring gaps to achieve consistent, reusable skill definitions.

Agents ignore documentation when rationalizations exploit gaps in the instructions. Fix this by running baseline failure scenarios, observing the exact deviations, and iterating on the skill definition until full compliance is achieved.