The file that defines a skill
SKILL.md is the entry point for an agent skill. When you install a skill, this is the file the agent reads to learn two things: when the skill applies, and how to carry it out. Everything else in a skill folder — reference docs, templates, helper scripts — exists to support what SKILL.md describes.
It is a plain Markdown file. That is deliberate. You can open it in any editor, read it top to bottom, and understand exactly what your agent will do before you let it run.
The two jobs of SKILL.md
A well-formed SKILL.md does two distinct jobs.
First, it announces itself. A short metadata section at the top usually gives the skill a name and a description. The description is more important than it looks: it is the signal the agent uses to decide whether this skill is relevant to the task at hand. A vague description means the skill triggers at the wrong time or never triggers at all.
Second, it instructs. The body explains the workflow in clear steps. Good bodies read like a careful runbook: do this, check that, format the output this way, watch out for this edge case. The instructions are written for an agent, but they should make sense to a human reading over its shoulder.
A simple shape
Most SKILL.md files share a similar layout. They open with metadata, then a one-line statement of purpose, then the steps. Many also include a short list of when not to use the skill, which is just as valuable as knowing when to use it.
The instructions stay focused on one workflow. If you find a SKILL.md trying to cover three unrelated jobs, that is usually a sign it should be three skills.
Progressive detail
A nice property of the SKILL.md pattern is that the main file can stay lean while pointing to deeper material when needed. Instead of dumping a thousand lines of edge cases into one file, a skill keeps SKILL.md concise and references supporting documents the agent can open only when the situation calls for it. This keeps the agent's attention on what matters and avoids drowning it in detail it rarely needs.
How to read one before installing
Reading SKILL.md is the single best habit you can build around skills. Before you install anything, open the file and ask: Is the trigger description specific? Do the steps make sense? Does it call any scripts, reach out to the network, or touch credentials? If the answer to any of those is unclear, do not install it yet. A skill you cannot understand is a skill you cannot trust.
This is exactly the kind of check covered in how to evaluate agent skills, and it is central to whether agent skills are safe.
Writing your own
Once you have read a few good examples, writing your own SKILL.md is approachable. Start with the workflow you know best, describe its trigger in one sharp sentence, and lay out the steps the way you would explain them to a careful colleague. You can browse the development category for patterns worth borrowing.
Common mistakes to recognize
Reading enough SKILL.md files teaches you to spot weak ones quickly. A few patterns recur. The most common is the vague description that tries to be broadly useful and ends up triggering at the wrong moments — a trigger that says "for general help" tells the agent nothing actionable. Another is scope creep: a single file that tries to handle several unrelated jobs, which makes the instructions tangled and the behavior unpredictable. A third is the silent script — a SKILL.md that quietly invokes helper code without explaining what it does, which should make any reader pause.
Knowing these anti-patterns is useful in both directions. It helps you avoid them in skills you write, and it helps you reject them in skills you might install.
How the agent uses the file at runtime
It helps to picture what happens when you give your agent a task. The agent looks at the available skills and reads their descriptions to decide which, if any, are relevant. When a description matches the work at hand, the agent loads that skill's instructions and follows them, opening supporting files only as the steps call for them. This is why the description carries so much weight: it is the gatekeeper that determines whether your carefully written steps ever get used. A brilliant body with a weak trigger is a skill that rarely runs.