How to Write an Agent Skill (SKILL.md): Structure, Trigger Descriptions and 5 Common Mistakes

A Skill is a folder that packages a reusable way of doing something for an AI, built around a single SKILL.md file. This guide explains what goes into SKILL.md, why the description decides whether the Skill gets used at all, what belongs in supporting files, and the 5 most common mistakes people make when writing Skills.

how to write an Agent SkillSKILL.md formatClaude Skills tutorialCodex Skillsagent skill description best practices

If you find yourself explaining the same steps, format and caveats to an AI every time you run a task, it's time to turn that into a Skill. A Skill is essentially a folder: a SKILL.md file spells out when to use it and how to do the job, with scripts, reference material and templates added as needed. Normally the AI only sees each Skill's name and a one-line description, and reads the full text only when it decides the Skill is relevant, so you can install dozens of Skills without crowding the context window.

The three parts of SKILL.md

The first part is the metadata at the top, and the key fields are name and description. The name is a short identifier; the description explains in a sentence or two what the Skill does and when it should be used. The second part is the body, which lays out the actual steps: what to do first, what comes next, what format to output, and how to handle exceptions. The third part is supporting files kept in the same folder, such as data-processing scripts, long specification documents and output templates, with the body saying when to read which file.

The description decides whether it gets called

Plenty of well-written Skills never get used, and the reason is almost always the description. The AI relies on the description to decide whether a request calls for this Skill, so it needs to be as specific as a search query: spell out how users will phrase the request, what kinds of files it handles, and what it produces. “Helps with documents” is too vague. “Turns meeting recording transcripts into meeting notes with action items; use when the user mentions meeting notes, cleaning up a recording, or a post-meeting summary” is much clearer.

Write steps in the body, not explanations

The body is something the AI executes, not a manual for humans to read. Use numbered steps with one action per step. Spell out conditions, for example “if the file is longer than 100 lines, split it first.” One complete input/output example is more useful than three paragraphs of principles. For anything that needs to be done precisely, like format conversion or calculations, write it as a script and put it in the folder, so the AI calls the script instead of rewriting the logic each time.

The 5 most common mistakes when writing a Skill

One: the description is too generic, so the Skill doesn't trigger when it should and triggers when it shouldn't. Two: cramming everything into SKILL.md. A body that runs thousands of words has to be read every time, which is slow and makes it easy to miss what matters; long material should be split into supporting files. Three: stating principles without examples. The AI's idea of “concise and professional” isn't the same as yours. Four: no testing. Instead of shipping it as soon as it's written, prepare a few real requests and check whether it gets called correctly and whether the output holds up. Five: putting API keys or account credentials in the Skill. Skills often get shared and copied, so sensitive information belongs in environment variables.

From personal Skills to enterprise skill packs

A Skill for your own use just needs to work. To share one across a team or a company, you also have to think about version control, security review, quality evaluation and centralized distribution. That's the gap between “a Skill that works well” and “an enterprise Skill pack.”

Illustrated Skill covers this in 56 illustrated lessons (lessons are in Chinese). It starts with how Skills work, then takes you from a paper sketch, step by step, to a skill pack that has been tested, passed security review and is ready to publish to an enterprise SkillHub. The first 6 lessons are free.