writing-skills

To write concise documentation for new Skills, use a TDD-driven authoring process that enforces standard frontmatter, a three-section description, and a search-optimized request field. This ensures your Skills remain easy to discover and reuse.

The TDD approach for skill authoring is a structured workflow where you write a baseline RED scenario, create a GREEN Skill, and run iterative REFACTOR checks. It tracks rationalization and uses example-driven quality checks before deployment.

Structure SKILL.md frontmatter by including exact name and description fields, then validate required metadata like dependencies and components. Follow the prescriptive template to ensure required fields and a three-sentence search-optimized request are present.

The best way to create a search-optimized request field is to write a precise, three-sentence request field specifically designed for vector embedding. This structured search field improves Skill discovery and reuse across the platform.

You should separate larger references into dedicated files when writing documentation to support progressive disclosure. Produce a compact reference within the main file first, then split larger references out as needed to maintain concise docs.