writing-skills

Test-driven development for skill documentation uses red-green-refactor cycles to draft, verify, and deploy SKILL.md files. You write a baseline pressure scenario before implementation, then refine the documentation until it passes defined quality checks.

SKILL.md frontmatter requires YAML syntax containing name and description fields. Descriptions must be concise and trigger-focused, ideally starting with 'Use when...' to ensure consistent quality checks before deployment across the skill namespace.

Validate skill readiness using a deployment checklist that reviews common pitfalls and red flags. Structured guidance ensures documentation captures intended behaviors and edge cases, confirming the skill passes all quality assurance checks.

TDD workflows apply to both drafting and revising skill definitions. The red-green-refactor cycle evaluates existing SKILL.md entries against baseline tests, ensuring structured updates maintain description quality and trigger accuracy.

A SKILL.md file should include structured sections for overview, triggering conditions, core patterns, quick start, and deployment readiness. Optional references to scripts or assets can be added to support the skill's intended behaviors.

Skill documentation fails quality assurance when it lacks structured sections, proper YAML frontmatter, or trigger-focused descriptions. Documenting narrative explanations instead of intended behaviors and edge cases also causes deployment readiness failures.