write-a-skill

To create an agent skill, draft a root SKILL.md file with YAML frontmatter containing required discovery fields, then organize supporting reference and utility files separately to enable progressive disclosure of workflows and advanced features.

Progressive disclosure in agent skill authoring is a documentation structure where a concise description enables discovery, while specialized workflows and deterministic content are bundled into supporting reference files to prevent overloading the root SKILL.md.

A SKILL.md file must include YAML frontmatter with required discovery fields like name and description, task triggers, domain scope, and references to any bundled utility scripts or reference materials needed for workflow execution.

You need to bundle separate reference files when skill content becomes too large or specialized for a single SKILL.md, ensuring deterministic instructions and advanced features remain discoverable without cluttering the root prompt instructions.

Agent skill authoring supports both approaches: you can build capability packs with only prompt instructions, or include executable utility scripts if the task domain requires deterministic execution alongside the YAML frontmatter and documentation structure.

The best way to structure long documentation is keeping the root SKILL.md concise with triggers and scope, then moving detailed workflow templates and specialized resources into bundled reference files that agents access through progressive disclosure.