write-a-skill

To create an agent skill, you need to scaffold a skill directory containing a SKILL.md file with YAML frontmatter for the name and description, a concise instructional body, and optionally bundled reference files or deterministic scripts to support progressive disclosure.

Progressive disclosure in skill authoring is a structural design pattern that splits long operational instructions into separate reference files, allowing the agent to load concise triggers first and access detailed workflow documentation only when needed.

You structure a SKILL.md file by defining YAML frontmatter with the skill name and description, writing a concise instructional body for the workflow triggers, and organizing any deterministic scripts or references into a maintainable skill directory layout.

You should include deterministic scripts in your skill directory only when a specific workflow requires exact, repeatable processing steps that cannot be reliably handled by the agent through standard operational instructions and reference files alone.

Yes, you can bundle reference files alongside operational instructions in a skill directory to provide deeper domain context, which the agent can load on demand based on the specific use case triggers defined in your SKILL.md.