Write skill metadata an agent can recognize

An agent skill starts with a directory containing SKILL.md. The Agent Skills specification requires a name and description in YAML frontmatter, followed by the instructions ^[1].

Make the description say when to use it

The specification's minimal structure is ^[1]:

skill-name/SKILL.md

---
name: skill-name
description: A description of what this skill does and when to use it.
---

Replace the placeholders with your task. The name must match the directory. Describe both the work and the circumstances that should trigger it ^[1].

Keep the procedure in the body

Put the instructions after the frontmatter. The specification allows supporting scripts, references and assets beside SKILL.md ^[1]. Link the exact supporting file where the agent needs it.

Anthropic describes progressive disclosure: skill metadata is available first, while the full instructions and additional resources load when needed ^[2]. A vague description can make a useful procedure hard to discover.

Check the behavior in a real task

Ask the agent to perform a task the description covers, then one outside that scope. Inspect which skill it selects and whether it loads the intended references. Revise the trigger description if it repeatedly selects the wrong procedure.