What is a SKILL.md, really?
A SKILL.md is not a prompt, not a plugin, and not an agent. It's a folder of expertise your agent only loads when it's needed.
A skill is conditional knowledge in a folder.
A skill is a single folder on disk. Inside it: one SKILL.md file with YAML frontmatter, plus any supporting assets — templates, scripts, reference docs. The agent reads the frontmatter all the time, but only opens the body when your request matches.
That last sentence is the whole point. Skills are lazy. Their full content does not live in the model's context. Only the short description field does. When you say something that matches that description, the agent reaches into the folder, loads the body, and uses it for the rest of the task.
This is what makes a skill different from a system prompt, a README, or "instructions you paste at the start of every chat." Those are always on, always burning tokens, always crowding out whatever else the model needs to think about. A skill only shows up when it's relevant.
The smallest possible SKILL.md.
Two pieces: a frontmatter header that tells the agent when to load you, and a body that tells it how to behave once it has.
--- name: brand-voice description: Apply the company's brand voice and tone rules when writing user-facing copy, marketing pages, or error messages. WHEN: drafting microcopy, writing release notes, polishing product descriptions. --- # Brand Voice We write in first person plural, in short sentences, and we never use the word "leverage." ## When to apply - Marketing pages and landing copy - In-product empty states and error messages - Release notes ## Rules 1. Verbs over nouns. "Ship it," not "shipment." 2. Cut every adverb. If it survives a re-read, keep it. 3. No em-dashes in product copy. Use commas or periods.
That's a working skill. The name is the folder's identity. The description is what the agent reads on every turn — it has to be specific enough that the agent can tell when you need it and when you don't. The body is the actual expertise, written for the agent to read like a teammate's note.
Notice what's not in there: no code that runs, no API to call, no special syntax. A skill is just markdown.
What a skill actually does.
Every skill, regardless of topic, is doing one or more of these three things. If your draft doesn't match any of them, it probably wants to be a different kind of file.
Carries domain knowledge.
Things the model can't infer from your codebase alone: your company's API conventions, the way your team writes ADRs, the exact wording your legal team approved, the steps for an internal release.
Encodes a workflow.
A sequence the agent should follow when a certain kind of task shows up: "before refactoring this module, run these checks," or "when writing a migration, always pair it with a rollback note."
Bundles assets.
Templates, example outputs, configuration files, small scripts the skill tells the agent to run. The folder is the skill — the markdown just tells the agent what's inside and when to use it.
Is this a skill, or is it something else?
Most new authors over-skill. They turn every preference into a folder. Use this gut-check before you scaffold one.
Yes — make it a skill
- It's expertise the agent needs sometimes, not always.
- It bundles knowledge plus assets (templates, examples, scripts).
- It describes how to do a kind of work, not what to do this turn.
- You'd want to reuse it across many conversations or projects.
- You can write a one-sentence description that says exactly when to load it.
No — try a different file
- It's a rule that should fire automatically on certain files →
.instructions.md - It's a single command you run from a menu →
.prompt.md - It's a persona the model should adopt for a whole task →
.agent.md - It's one-off context for today's chat → just paste it in the chat
- It's documentation for humans → a regular README
Watch what the agent actually loads.
Same user request. One repo without a skill, one repo with. Tap a tab to see what the agent's context window looks like the moment it reads your message.
[user] Write a release note for v2.4.
The agent has nothing to lean on. It guesses your voice, your format, the words you'd never ship. You correct it. Three turns later you give up and write it yourself.
[user] Write a release note for v2.4. [skill: brand-voice] We write in first person plural, in short sentences, and we never use the word "leverage." ## Rules 1. Verbs over nouns. 2. Cut every adverb. 3. No em-dashes in product copy.
The agent loaded the skill body only because your message matched the description. On every other turn this folder stays asleep.
The folder stays asleep until your words match.
Watch what "lazy" looks like. Messages drift past a dormant skill folder. Only when one matches the description does the folder open and pour its body into the agent's context.
verbs over nouns
cut every adverb
no em-dashes in product copy
Most messages pass by untouched. The one that matches the skill's description is the one that opens it.