Write your first Agent Skill the way Anthropic does
A skill is a folder with a SKILL.md. Learn the minimal format and where to copy patterns from.
TL;DR
A skill is a folder containing a SKILL.md with two required frontmatter fields, name and description, followed by instructions the agent loads on demand.
Why this repo matters
It is the official reference collection. The skills range from creative and design work to testing web apps and generating MCP servers, and the repo also holds the Agent Skills spec and a skill template.
Best practices
- Keep each skill self-contained in its own folder.
- Write the
descriptionto say what the skill does and when to use it; the agent uses it to decide when to load the skill. - Use lowercase and hyphens for
name. - Put instructions, examples and guidelines in the markdown body, and scripts or resources next to it.
- Start from the repo's
templatefolder instead of a blank page. - Test in your own environment. The repo says its skills are demonstrations, not guarantees.
How-to
Where do I start?
1. Create the folder and file
Make my-skill-name/SKILL.md.
Try it
Copy the template folder, rename it, write a description for a task you repeat weekly, and ask your agent to do that task.
Pitfalls
- A vague description means the skill never triggers.
- Treating the examples as production-ready without testing them.
- Mixing several unrelated jobs in one skill.
Next steps
Read the spec folder, then browse the skills folder for a pattern close to your task.