writing-skills

To write SKILL.md documentation that Claude discovers reliably, start with required YAML frontmatter containing name and description fields, then add a concise body following skill writing guidelines to ensure the file is loadable and testable.

Test-driven documentation for skill authoring applies a RED-GREEN-REFACTOR cycle to SKILL.md creation, treating documentation as a testable artifact to enforce discipline and ensure repeatable, testable skill instructions.

You do not need scripts and references to create a valid Skill; a minimal SKILL.md with name and description frontmatter is required, while scripts, references, and assets are optional layers for progressive disclosure.

The best way to structure Skill documentation for progressive disclosure is to keep the core SKILL.md minimal and load optional references, scripts, and assets on demand rather than embedding all content upfront.

You should apply the RED-GREEN-REFACTOR workflow to skill development whenever you draft a new Skill or edit an existing SKILL.md across the Skills library, ensuring systematic agent guidance and repeatable quality assurance.