writing-skills

Test-driven development for documentation involves writing minimal SKILL.md files and iterating through RED-GREEN-REFACTOR cycles, ensuring skills fail without tests and pass when implemented against agent behavior.

The best way to structure a SKILL.md file is using YAML frontmatter with name and description fields, keeping the document concise, and applying progressive disclosure by cross-linking to heavy references, scripts, and tooling.

The RED-GREEN-REFACTOR cycle for skill writing validates skills against agent behavior by tracking rationalization, ensuring documentation fails without tests initially and passes once the skill is correctly implemented and refactored.

Yes, YAML frontmatter containing name and description is required to validate skill documentation, as it enables progressive disclosure and ensures the skill unit is self-contained and discoverable by Claude agents.

Yes, you can expand skill documentation by adding optional references, scripts, and assets directories alongside the core SKILL.md file, facilitating progressive disclosure and cross-linking to heavy tooling as needed.

Skill documentation fails validation without tests because the test-driven development approach ensures skills are built and validated before deployment, requiring implementation to pass the RED-GREEN-REFACTOR verification workflow.