write-a-skill

To create reusable agent skills, draft a concise SKILL.md file containing frontmatter, core instructions, and a practical workflow to define the skill's behavior. This structure ensures the agent can easily load and trigger the instructions.

Progressive disclosure in skill authoring is an approach that keeps the main SKILL.md concise while moving deeper knowledge into optional reference files. Agents load primary instructions first and access bundled references only when deeper context is needed.

You should add bundled reference files or scripts to an agent skill directory when the workflow requires deeper domain knowledge or deterministic task execution. This separates heavy content from core instructions, optimizing the agent's loading process.

Structure a skill directory by keeping the core logic in a concise SKILL.md file and splitting content into separate reference files when the instructions become too extensive. This organization supports trigger-aware descriptions and clear content boundaries.

The best way to write trigger-aware descriptions is to clearly define the use cases and trigger conditions within the SKILL.md frontmatter and instructions. This ensures the AI agent accurately identifies when to activate the specific workflow.