Definition
An agent skill is a short document, often a file named SKILL.md, that tells an AI agent how to handle a specific kind of task. Think of it as a checklist for an experienced pilot: the pilot already knows how to fly, and the checklist exists to make the important choices repeatable and to prevent known mistakes. Write it for a reader that is capable, literal, and relies only on what you wrote down.
You’ve probably typed the same instruction to an AI agent more than once.
“Ask me one question at a time.”
“Run the test instead of mocking it.”
“Group the changelog by what the user sees.”
A skill saves an instruction like that so you don’t have to type it again. It’s usually a short file named SKILL.md that tells an agent how to handle a specific kind of task. Writing one sounds simple; the tricky part is knowing what belongs in the file.
A useful way to decide is to think about the reader. Picture an agent that is capable, literal, and starting fresh. It already knows a lot, but it only has the instructions and context available to it right now.
✦Go deeperThe classic names for this readeropen +close −
The three properties have older, sharper names: brilliant, literal, and amnesiac. Brilliant, because the model has read more about your domain than you will ever write down. Literal, because it performs the sentence you wrote, not the sentence you meant. Amnesiac, because the safest assumption is that nothing carries over.
This is a writing aid, not a description of how any one agent system works. It’s useful precisely because it doesn’t depend on any system’s internals.
The companion picture is the pilot’s checklist. The pilot already knows how to fly. The checklist doesn’t teach flying. It makes the important choices repeatable, and it prevents known mistakes. That’s the whole job of a skill.
This is step 1 of a five-step lab. By the end, you’ll have a skill you have tested and can publish for other people to use.
Your agent already knows a lot
You do not need to teach the model everything you know about programming, writing, testing, or software design. Spend your skill on the things it could not know on its own:
- the process you want it to follow
- the rules that matter for this task
- your team’s conventions
- decisions your team has already made
- mistakes you specifically want to prevent
Compare these two instructions:
The model already knows it should write good tests, so the first line changes very little. The second changes what happens next.
A skill should spend its words on that second kind of information.
The agent follows what you wrote, not what you meant
Humans are good at filling in missing context. If a coworker knows you well, you can say something vague and they may still understand what you intended. An agent may follow the sentence much more literally. So if what you really want is a conversation, say that:
You may imagine a back-and-forth conversation. With the first version, the agent could reasonably ask ten questions in one message. The second leaves less work for the reader to guess.
Here’s the same failure, caught in the wild:
The sentence didn't fail. It was obeyed.
If a question can be answered by reading the code, read the code instead.
A line from pushback, written for a live session. The author meant: don't waste my time with lookups. A human reader repairs that meaning from context. (The wavy word is the one to watch.)
When you write a skill, ask: If someone had only this sentence, would they know what I want them to do?
Don’t rely on the agent remembering something you didn’t write down
Some agent tools can remember information across a session or even across sessions. Do not make your skill depend on that. Write the skill so it still works when the agent starts with no knowledge of the conversation where you created it — put the important instruction in the skill, or link to the file that contains it:
Your skill should make sense to an agent using it tomorrow, in another session, or as part of another workflow.
Only keep lines that change behavior
Here’s a useful test for every line in a skill: Would the agent behave differently if I removed this sentence? If the answer is no, the sentence probably does not need to be there.
A line like “Write clearly and concisely” changes very little. But “Group changelog entries by user-facing feature, not by internal module” changes a specific decision, and “One merged change gets one line; leave out changes with no user-visible effect” changes behavior too. This is sometimes called the no-op test: if removing the line changes nothing, the line is doing no work.
Which lines change behavior?
Five lines from a draft of to-changelog. For each one: does it change what the agent does, compared to what it would do anyway?
0 / 5 judged
You do not need every instruction to be extremely specific, and some skills should leave room for judgment. The question is simply whether the instruction gives the agent something useful that it would not otherwise have.
✦Go deeperWhy every line has a priceopen +close −
Words in a skill aren’t free, because a skill has to be carried. If the agent discovers the skill on its own, a note about it rides in the agent’s working memory (its context) so it knows the skill exists. If you invoke it by name, you carry the memory that it exists instead. Either way, a line that changes nothing is rent paid for nothing.
How much context a skill costs depends on the tool running your agent; most modern tools keep a light summary visible and load the full skill only when needed. Step 2 covers how to choose who invokes yours, and skill invocation covers the mechanics.
A good skill makes the important parts more reliable
The goal of a skill is not to make every run identical. The goal is to make the behavior you care about more dependable: the right steps happen in the right order, an important rule is not forgotten, a known mistake is avoided, the agent asks before taking a risky action, your team’s convention gets followed consistently.
The first leaves almost everything up to the agent. The second makes an important part of the result predictable while still leaving the agent room to write.
Which line makes the intended behavior more reliable?
A skill is judged by what it makes more likely: the intended procedure chosen, the constraints obeyed, the known failure modes avoided. Which line does that here?
0 / 3 judged
That’s what a useful skill does: it reduces variation where variation causes problems.
✦Go deeperReliability, not samenessopen +close −
This quality has a name: reliability. It is not the same as sameness, and the cockpit checklist is again the right picture. Even experts skip steps under pressure; the checklist exists for exactly that. It doesn’t make every flight identical — weather and judgment stay with the pilot. It makes the important actions dependable. When you judge a skill, don’t ask whether every run went the same way. Ask whether the right behavior became more likely.
Your turn
Think of one instruction you have already given an agent more than once. Don’t turn it into a polished skill yet; just write down the instruction in the words you would normally use. Then ask three questions:
- Am I telling the agent something it already knows?
- Could the agent interpret this differently than I intend?
- Does this instruction depend on context that is not written down?
You don’t need to fix everything yet. In the next step, you’ll take an instruction that already works and turn it into the smallest possible first draft.
Where this path goes next
The rest of the lab follows one simple loop:
- Start with an instruction that already works.
- Save the smallest useful version.
- Run it and see what goes wrong.
- Fix only what the failures teach you.
- Test the finished skill and publish it.
Next: capture your first draft.