writing-skills

Test-driven documentation for agent skills is created by applying a RED-GREEN-REFACTOR workflow to describe the problem solved, applicable contexts, and required structure, reducing drift between documented guidance and actual behavior.

The RED-GREEN-REFACTOR workflow for skill creation is a disciplined testing approach that uses pressure-scenario testing formats and rationalization tables to validate SKILL.md files before finalizing the documentation.

To validate frontmatter and asset directories in SKILL.md files, you enforce frontmatter validity requirements for name and description, while checking optional scripts, references, and assets directories to extend guidance.

Progressive disclosure structure works for lightweight skill references by embedding inline guidance directly in the SKILL.md file, allowing users to access concise examples and test scenarios without overwhelming the documentation.

You can use pressure-scenario testing to validate subagents documentation by applying rationalization tables that test the documented workflow against edge cases, ensuring the subagents behave as described under pressure.

Limitations of test-driven skill documentation include the strict requirement for frontmatter name and description fields, meaning the framework cannot validate skills lacking these mandatory metadata entries or those bypassing the RED-GREEN-REFACTOR process.