writing-skills

Skill documentation uses a RED-GREEN-REFACTOR workflow to prevent untested behaviors. You write a SKILL.md file with frontmatter for name and description, then validate the Markdown body and optional scripts through failing baseline tests before deployment.

The RED-GREEN-REFACTOR workflow for skill development is a test-driven cycle: write failing baseline tests for skill documentation (RED), validate the SKILL.md to pass tests (GREEN), and refine the structured Markdown body and references (REFACTOR) before deployment.

Structure a SKILL.md file with frontmatter for name and description, followed by a structured Markdown body. Use multi-file reference patterns and optional scripts to keep context concise and support cross-skill references for deployment readiness.

Test-driven skill documentation applies to creating and validating new skills across teams and projects, especially where skills guide agent behavior and require testing before deployment. It establishes a disciplined workflow for consistent results.

The best way to validate skill deployment readiness is to apply a deployment checklist including testing steps within a RED-GREEN-REFACTOR cycle. This prevents common rationalizations and ensures the SKILL.md and optional assets are fully tested.