write-a-skill

To create reusable agent skills, you need a root SKILL.md file with YAML frontmatter and concise operational guidance. This structures capabilities, use cases, and progressive disclosure for assistant behavior.

Progressive disclosure in skill authoring provides the right amount of context to an agent at the right time. It structures instructions so agents load operational guidance and optional resource files only when needed.

You structure optional scripts and references using a clean folder structure for on-demand loading. Organize supporting assets alongside the root SKILL.md so the agent accesses deeper documentation or deterministic actions only when required.

Yes, you need YAML frontmatter in the root SKILL.md file to build a new agent skill. It defines the skill's metadata, ensuring the capability is easy to discover, maintain, and clear about when it should be used.

The best way to turn a task domain into a capability is defining the skill's purpose, target use cases, and required resources before writing instructions. This planning phase ensures concise guidance and proper resource organization.

You should not rely solely on a single SKILL.md file when your skill needs deterministic actions or deeper documentation. In these cases, add optional scripts, references, and assets organized for on-demand loading.