writing-skills

Test-driven skill documentation requires a RED-GREEN-REFACTOR validation cycle during development. You define test cases first, write the SKILL.md to pass them, and then refactor for progressive disclosure and metadata validity.

Progressive disclosure in skill writing is a pattern that keeps core guidance concise in SKILL.md while pushing detailed references and optional assets into separate linked files. This ensures agents parse instructions reliably without context overload.

Validating YAML frontmatter for skill creation involves checking mandatory name and description fields against strict constraints. The validation process ensures metadata is CSO-ready and structurally sound for agent discovery and enforcement.

The best way to structure SKILL.md for discoverability is combining valid YAML frontmatter with concise, reusable content blocks. Optimizing metadata via CSO guidelines ensures agents can reliably locate and enforce the skill during execution.

No external dependencies are required to enforce testing cycles for skill writing. The validation workflow operates independently using RED-GREEN-REFACTOR principles and internal deployment guidelines to prevent rationalizations and ensure bulletproof skills.

Skill metadata fails discovery validation when YAML frontmatter lacks required name and description fields or violates CSO guidelines. Running the prescribed testing workflow catches these structural defects early in the development cycle.