write-a-skill

To structure and document a new AI skill, create a SKILL.md file with frontmatter specifying the name and description, then add optional REFERENCE.md, EXAMPLES.md, and scripts directories to organize resources and deterministic tasks.

The recommended folder layout for agent skill creation includes a root SKILL.md file with frontmatter, alongside optional REFERENCE.md for detailed context, EXAMPLES.md for use cases, and a scripts directory for helper code.

Yes, frontmatter in SKILL.md is required to document agent skills, as it must explicitly define the skill name and description to ensure consistent layout and proper agent recognition across projects.

A guided workflow helps standardize AI skills by providing a step-by-step process from requirements capture to drafting and review, ensuring consistent layout, reducing setup time, and eliminating documentation ambiguity.

You should add REFERENCE.md or EXAMPLES.md to your skill directory when your agent requires additional context or use case demonstrations, bundling reusable resources to accelerate skill creation and clarify complex tasks.

The best way to create consistent templates for multiple AI skills is using a standardized blueprint with SKILL.md frontmatter and a clear folder structure, applying reusable resources like helper scripts to accelerate setup.