A trigger
The description tells the agent which user requests should activate the skill.
See the frontmatterA starter guide for new authors. Learn what a skill is, how it loads, and how to write one your agent will actually find.
A SKILL.md is a single Markdown file that teaches your agent when to use a capability and how to use it. The frontmatter is the trigger. The body is the instructions. That's it.
The description tells the agent which user requests should activate the skill.
See the frontmatterThe body is plain Markdown. Steps, examples, code, do/don't lists — whatever your agent needs.
See the bodySkills are loaded lazily. Write them so the agent knows whether to commit before reading the whole file.
See the rules--- name: my-first-skill description: Generates a starter README from a project description. WHEN: "write a README", "create project docs", "scaffold README.md". DO NOT USE FOR: editing existing READMEs. --- # My First Skill ## When to use this Trigger this skill only when the user wants a **new** README created from scratch. ## Steps 1. Ask for project name and one-line purpose. 2. Generate sections: Overview, Install, Usage. 3. Write to README.md at the repo root. ## Don't - Don't overwrite an existing README without confirming with the user.
Two fields matter: name and description. The description is the only thing the agent reads to decide whether to load your skill — make it specific.
Spell out trigger phrases and anti-patterns. This is the single biggest reason skills get invoked correctly.
Headings, lists, code blocks, links to other files. Keep it scannable — the agent reads top-to-bottom.
For long examples or assets, link to sibling files (./templates/readme.md) instead of stuffing everything into SKILL.md.
Finish this sentence: "I want my agent to do X when the user says Y." X is the skill. Y is the description.
Three sections is plenty: When to use, Steps, Don't. Add examples only if they change behavior.
Ask your agent the exact phrase from your description. If it doesn't load the skill, the description is too vague — rewrite and retry.
Copy the anatomy block above into a new SKILL.md, rename the file's parent folder, and you're done. Your agent will pick it up on the next session.