writing-skills

Test-driven skill writing involves drafting failing baseline tests for your SKILL.md, then composing the documentation to pass them through RED-GREEN-REFACTOR cycles. This ensures baseline failures are captured and addressed before deployment.

A reliable SKILL.md requires YAML frontmatter with name and description fields, followed by a concise body defining triggering conditions, patterns, and minimal implementation details. This discovery-friendly metadata improves Claude's retrieval and loading decisions.

You validate existing skill definitions by running RED-GREEN-REFACTOR cycles to verify consistent frontmatter and navigable content. This process checks agent rationalizations and ensures baseline failures are addressed before deployment.

No, skill writing uses progressive disclosure guidance to structure frontmatter with clear sections and link heavy references only when needed. The SKILL.md body should contain minimal implementation details rather than exhaustive documentation.

Agent rationalizations are recorded during the RED phase when baseline tests fail, then verified for compliance during the GREEN phase. This TDD-driven approach ensures the final skill definition meets the required behavior.

Automating skill documentation quality checks requires applying test-driven development patterns to capture and address baseline failures. This ensures consistent frontmatter structure and navigable content across newly created or edited skills.