writing-skills

To structure a SKILL.md for optimal discovery and safety, use a standardized YAML frontmatter with mandatory name and description fields, apply progressive disclosure for body content, and link to external references for heavy resources.

Progressive disclosure in skill writing is layering content via linked references rather than using monolithic documents. Use this technique when authoring skills to reduce token usage and minimize load during execution.

Validate frontmatter by ensuring mandatory YAML fields are present and correct, then apply quality gates like CSO alignment and red-blue-green testing patterns to execute safe deployment checks before sharing your skill.

The best way to balance token efficiency with completeness is organizing skill documentation with a concise body that links to references or scripts for heavy guidance, validating frontmatter and body organization to avoid bloated monolithic files.

No dependencies or components are required to create a standardized skill workflow. You can structure a new Skill MD with minimal frontmatter and a concise body, then link to references or scripts for heavy guidance.

Skill documentation fails reliable indexing and discoverability when it lacks frontmatter discipline. Enforcing YAML frontmatter with mandatory fields like name and description ensures your skill is properly indexed and discoverable.