writing-skills

Test-driven skill documentation uses a RED-GREEN-REFACTOR workflow: draft a SKILL.md with YAML frontmatter, write a failing RED baseline test, implement the skill to pass GREEN, and refactor to close loopholes before deployment.

Structure process documentation by adding YAML frontmatter with name and description in SKILL.md, then separate heavy API references and tooling into optional scripts, references, and assets folders to keep inline content light.

Validate skills before deployment by running a discovery and QA workflow that tracks rationalization and red flags, ensuring your baseline tests stay GREEN after iterating on the skill implementation.

Yes, you can modularize heavy API references by separating them into optional scripts, references, and assets directories, keeping the light inline content focused on progressive disclosure and cross-skill references.

A failing baseline test is needed first because the RED-GREEN-REFACTOR lifecycle requires a RED baseline to validate that your skill implementation passes GREEN and aligns documentation with real agent behavior before deployment.