writing-skills

Creating a structured AI skill requires following a documented pattern: define a two-field YAML frontmatter with name and description, then build a SKILL.md with sections including Overview, When to Use, Core Pattern, Quick Reference, Implementation, Common Mistakes, and Real-World Impact. This enforces consistency and makes skills reusable and maintainable.

Test-driven documentation is a RED-GREEN-REFACTOR workflow that validates skills before deployment by using pressure scenarios with subagents to surface failures. It ensures your skill meets compliance requirements and performs reliably under real conditions before going live.

Validate skills by enforcing test-driven documentation: run pressure scenarios with subagents to uncover edge cases and failures, verify your SKILL.md complies with the required structure and frontmatter format, and confirm the skill handles common mistakes gracefully before deployment.

Maintainable AI skills require a consistent documentation structure: two-field YAML frontmatter, an Overview section explaining purpose, When to Use guidance, a Core Pattern describing the approach, Quick Reference for fast lookup, Implementation details, Common Mistakes to avoid, and Real-World Impact examples showing practical outcomes.

Yes, this skill guides editing existing SKILL.md files by applying the same best-practice structure and test-driven validation. Restructure your documentation to match the required layout, validate against pressure scenarios, and ensure compliance with the two-field frontmatter before re-deploying.