writing-skills

Documenting skills using a test-driven approach requires writing a failing test first, then creating or editing a SKILL.md with YAML frontmatter defining name and description, and finally running deployment checks before publishing.

The NO SKILL WITHOUT A FAILING TEST FIRST principle enforces writing a failing test for skill documentation before creating the actual skill content, ensuring validation and reducing deployment drift within a disciplined RED-GREEN-REFACTOR workflow.

Structure a SKILL.md file for skill discovery by including YAML frontmatter with a strict name and description contract, followed by a well-structured Markdown body, and optionally adding scripts, references, and assets directories in the skill root folder.

Before publishing a skill, apply a structured deployment checklist that validates the YAML frontmatter contract, verifies cross-skill references for consistency, and confirms all RED-GREEN-REFACTOR workflow tests pass to ensure deployment readiness.

Editing existing skills without breaking cross-skill references requires applying a test-driven validation workflow that checks the structured deployment checklist and verifies frontmatter contracts to ensure reuse and consistency across related skills.

Skill documentation requires a RED-GREEN-REFACTOR workflow to formalize validation, reduce drift, and enforce deployment-ready checks, ensuring that every skill modification is tested before the final Markdown body and references are published.