writing-skills

Test-driven development for skill documentation uses a Red-Green-Refactor workflow to structure drafting, review, and refinement. This methodology ensures your skill docs remain consistent, maintainable, and deployable by validating readiness through test-like scenarios before publishing.

A valid SKILL.md file requires a frontmatter schema constrained to name and description. Enforcing this frontmatter validation ensures the skill can be properly discovered, loaded, and deployed across the knowledge base.

You validate skill documentation readiness by applying test-like scenarios during the Red-Green-Refactor lifecycle. This verifies that your SKILL.md has clear sectioning, valid frontmatter, and can be successfully discovered and loaded by the system.

Yes, the test-driven documentation approach supports both drafting new skills and updating existing ones. It guides the refinement lifecycle to ensure your updated skill documentation maintains consistency and deployability across the knowledge base.

The best way to structure a SKILL.md file for consistency is by ensuring clear sectioning and including a frontmatter block with name and description. Adhering to this constrained schema during the refactoring phase guarantees maintainability.

Skill documentation fails system discovery validation when it lacks the required frontmatter name and description fields or clear sectioning. Applying the Red-Green-Refactor workflow enforces these constraints to ensure successful loading and deployment.