Definition
The easiest way to draft an agent skill: take a successful instruction you have already given your agent and save it as the skill. Give it a name and a one-line description. Before you share it, remove anything private or tied to that one session. Add structure later, only when real use shows you need it.
Good first skills usually do not start with an empty template. They start with something much simpler: an instruction you have already given your agent and already know works.
Maybe you have typed:
Pressure-test every assumption, one at a time, until the plan holds up.
Or:
Group the changelog by what the user sees, not by the part of the codebase that changed.
You already did the hard part. You found words that changed the agent’s behavior, and your first version of the skill can start there.
Start with an instruction that already worked
A useful first skill is often hiding in something you have already typed several times. Take the example above:
Pressure-test every assumption, one at a time, until the plan holds up.
That sentence already tells the agent quite a lot. “Pressure-test” tells it what kind of thinking to do, “every assumption” tells it what to examine, and “one at a time” tells it how to pace the conversation. Click through the sentence and see how much work each word is doing:
One sentence, three jobs
No template produced this sentence. Its author had typed it enough times to know it worked, then saved it. Click a word — start with the wavy one.
You did not need a template to discover those instructions. You discovered them by working with the agent, and that is a good place to start. If you record your agent sessions, search them for instructions you repeat. Otherwise, look through prompt history or simply think about the corrections you find yourself making over and over.
✦Go deeperThis move has a name: captured speechopen +close −
Writers call a first draft like this captured speech — words you had already said enough times to know they worked, saved instead of composed. Nearly every well-obeyed skill starts this way, and it’s why the voice in your instruction is worth keeping: a charged verb like “pressure-test” carries more behavior than a section header ever will. Searching your recorded sessions for repeated instructions is a small, by-hand version of skill extraction.
Start with behavior, not structure
It can be tempting to start a new skill by creating a large template:
## Purpose
## Requirements
## Process
## Edge cases
## Examples
## Anti-patternsBut you do not know yet whether your skill needs all of those sections, and adding structure too early encourages you to solve problems you have not actually seen. Start with the behavior you know you want, then let real use show you what else the skill needs.
ship-review: 74 lines at launch
When the team wanted “a review skill,” they designed one. Six subsections, a severity rubric, a formal multi-reviewer process with structured write-ups per reviewer. It looked professional. It was obeyed badly.
A one-sentence skill that reliably changes behavior is more useful than a polished ten-section document full of guesses.
When should you turn an instruction into a skill?
A simple rule of thumb: if you have typed roughly the same instruction twice, consider saving it before you type it a third time.
It is not a hard rule, and it bends in both directions. Some instructions deserve a skill immediately: create one sooner when the process is risky, expensive, complicated, easy to forget, or shared by several people. You probably should not wait for three production database changes before writing down the safety rules. The opposite is true too. If you rewrite the instruction completely every time you use it, it may not be ready to become a skill yet — you may still be figuring out what you actually want the agent to do.
Save the first draft
Once you find an instruction worth keeping, your first draft can be very small.
1. Copy the instruction that worked
Start with the words you actually used, and do not make them sound more formal just because they are going into a file.
If the short version is the one that worked, keep it. Clarity matters more than sounding official.
2. Give the skill a name and description
A SKILL.md file begins with a small header called frontmatter:
---
name: pushback
description: Challenges a plan's assumptions one question at a time.
---Then put the actual instruction underneath it:
---
name: pushback
description: Challenges a plan's assumptions one question at a time.
---
Pressure-test every assumption, one at a time, until the plan holds up.That’s enough for a first draft. The name gives the skill an identity, and the description helps explain when the skill should be used.
Decide how the skill should be invoked
There are two common ways a skill gets used.
The agent can discover it
The agent sees information about the skill and decides when it applies. This is useful when you want the behavior to happen automatically — if you have a skill specifically for reviewing database migrations, you may want the agent to recognize a migration task and use the skill without being told.
When the agent discovers a skill automatically, the description matters a lot. It needs to make clear when the skill should and should not apply. The agent’s tool may also keep some information about available skills in its context so it knows they exist; exactly how that works depends on the agent tool you use.
You can invoke it yourself
You explicitly tell the agent to use the skill when you need it. The skill does not need to be discovered automatically, but now you have to remember that it exists. That can be a good trade when the skill is rarely needed, when you want tight control over when it runs, or when using it at the wrong time would be disruptive or risky.
Same skill, two kinds of load. Watch who carries it:
Who carries it?
Who carries it?
Discovery load — carried in context.
You do not need to optimize this perfectly on your first skill. Ask one question: do I want the agent to recognize when this skill applies, or do I want a person to choose when it runs? The exact controls depend on the agent tool you use, and you can look those up when you configure the skill.
| The agent discovers it | The behavior happens automatically. The description must say clearly when the skill applies — and when it does not. A note about the skill occupies the agent's context. |
|---|---|
| You invoke it | You control the timing. Nothing sits in context until you summon it, but you carry the memory that the skill exists. Good for rare, risky, or disruptive skills. |
✦Go deeperThe two costs, namedopen +close −
The trade has names. When the agent discovers the skill itself, the standing note in its working memory is discovery load. When you invoke it yourself, the cost moves into your head: recall load. Neither is free; they’re just billed to different parties.
The mechanics are tool-specific. In Claude Code, for example, a frontmatter line (disable-model-invocation: true) makes a skill yours to fire; other tools draw the line differently, and the details change over time. Write for the trade-off, which is the same everywhere, and look up the mechanics in skill invocation when you need them.
Clean up anything that should not travel with the skill
The instruction may have come from a real session, and that session probably contained details that do not belong in a reusable skill. Before you share the draft, remove passwords, API keys, private data, personal information, temporary file paths, ticket numbers that only mattered in that session, and names that should be replaced with a general role or category.
Keep the useful behavior. Remove the accidental details of the session where you discovered it.
Your first version is allowed to be small
Do not add every edge case you can imagine. You will be tempted to think: what if the agent asks too many questions? What if another skill calls this one? What if it misinterprets this word? Those might become real problems, but you do not know yet. Start with what has already earned a place in the skill.
There is one important exception: safety boundaries do not need to wait for a failure. If the skill can do something destructive or difficult to reverse — deleting data, deploying to production, handling credentials, moving money, changing access or permissions — put the boundary in the first version. You do not need to experience a real accident before writing those rules down. For everything else, let the skill meet real work first.
✦Go deeperWhy guessed lines are worse than missing linesopen +close −
Lines added before their problem exists have a name too: sediment. They settle into a skill because adding feels safe and removing feels risky, and the reader carries them forever whether or not they ever help. A missing rule announces itself the first time something goes wrong. A guessed rule just sits there, costing attention. That asymmetry is the whole argument for starting small.
Your turn
Find one instruction you have already used successfully, then work the checklist:
Four steps from utterance to v1
time-box the whole thing to ten minutes.
Do not add sections just because you think a skill is supposed to have them. Your goal is not a complete skill yet — it’s the smallest version that captures behavior you already know is useful.