writing-skills

Test-driven documentation applies a red-green-refactor loop by capturing baseline agent failures, refining the skill text to eliminate rationalizations, and re-testing to ensure compliance. Baseline testing without the skill is performed first, then the skill is implemented and re-tested.

Progressive disclosure in skill documentation organizes content using YAML frontmatter with name and description, a concise SKILL.md body, and optional support materials organized under scripts, references, and assets to prevent overwhelming the agent.

To stop rationalizing, capture baseline agent failures and build red-flag counters into the skill documentation to close loopholes. The skill is then refined under pressure through the red-green-refactor loop until the agent complies with the instructions.

Yes, YAML frontmatter containing the name and description fields is required to write a skill. A concise SKILL.md body is also required, while optional support materials can be organized under scripts, references, and assets directories.

The best way to validate documentation quality under pressure is to apply quality assurance testing by recording baseline failures, building red flags for rationalizations, and validating compliance through a progressive refinement loop.

You should avoid a red-green-refactor loop for skill writing when your documentation does not require strict quality assurance or when the skill operates without risk of agent rationalizations that need baseline failure capture and active loophole closure.