writing-skills

Test documentation to prevent skill drift by applying a Red-Green-Refactor cycle that captures baseline failures, implements minimal skill updates, and verifies compliance through structured pressure scenarios.

Test-driven documentation for skill authoring is a disciplined method that validates SKILL.md entries by recording rationalizations verbatim and enforcing progressive-disclosure structures to ensure correctness and repeatability across deployments.

Structure SKILL.md files for better search and reuse by enforcing minimal YAML frontmatter with a name and description, using a concise third-person description to maximize discoverability and maintain consistent documentation quality.

You can edit existing SKILL.md entries using a test-driven approach by designing pressure scenarios, observing failures without the updated skill, and re-testing until all validation tests pass before deployment.

The best way to validate skills before deployment is to run a structured testing cycle that verifies YAML frontmatter compliance, checks progressive-disclosure body content, and confirms all pressure scenario tests pass.