What an Agent Skill Is, and How to Write One
If you use an AI assistant for the same kind of task more than a few times, you have probably noticed the tax. Every session starts cold…
What an Agent Skill Is, and How to Write One
College Park, Maryland
If you use an AI assistant for the same kind of task more than a few times, you have probably noticed the tax. Every session starts cold. You re-paste the instructions, the format you want, and the list of things to avoid. The model does a decent job. Tomorrow you do it again. The model remembers none of it, so the remembering falls to you, every time.
A skill removes that tax. You write down how the task should be done, once, in a plain text file. You save it where your AI tool can see it. From then on, when a task matches, the model reads your instructions and follows them, without being asked and without being re-pasted. It works the way onboarding a new hire does: write the standard procedure well once, and everyone who reads it does the job the same way. The difference is that this new hire reads instantly and never forgets where you filed the document.
What a skill actually is
Strip away the branding and a skill is a folder with one required file in it, named SKILL.md. That file has two parts. The top is a short block of metadata in a simple key-and-value format, with two fields that carry the weight: a name, and a description of what the skill does and when to use it. Below the metadata sits the body, ordinary text, where you write the actual instructions in plain language. That is the whole format, a text file in the right folder, with no server and no code required.
A skill can carry more than instructions when it needs to. You can bundle example files, reference documents, or small scripts in the same folder, and the tool pulls them in only when the task calls for them. Most skills never need any of that. A single SKILL.md does the job.
How the model decides to use it
Your AI tool does not load every skill into its head at once. At the start, it reads only the name and description of each skill you have, just enough to know what each one is for. When you give it a task that matches a description, it reads that skill’s full instructions and follows them. If the skill carries extra files, it opens those only at the moment it needs them. The industry term for this is progressive disclosure, and the practical effect is that you can keep dozens of skills on hand while the model pays attention only to the one in front of it.
That mechanism puts enormous weight on the description. The model matches a task to a skill by reading the description and nothing else, so a vague description leaves the skill sitting unused while you wonder why nothing happened. Write the description to say plainly what the skill does and the specific situations that should trigger it. If anything, err toward casting a wide net, because the common failure is a skill that never fires rather than one that fires too often.
Writing your first one
Pick a task you do the same way repeatedly. The candidates are everywhere once you look: formatting your weekly status update, turning meeting notes into action items, drafting replies in your company’s voice, scaling a recipe, checking a contract for the clauses you always check. The test is simple. If you catch yourself explaining the same preferences to the model more than twice, those preferences belong in a skill.
Then write down what you would tell a capable stand-in who has never done the task. Be concrete. Give the steps, the format you want, the things to avoid, and one example of a good result, because a single worked example teaches more than a paragraph of description. Keep it in plain language, the kind a careful reader could follow without any technical background.
Say you want your emails to sound like you. Your SKILL.md might name itself personal-email-voice, describe itself as guidance for drafting and editing your work emails so they match your tone, and then in the body lay out what defines that voice: short sentences, no corporate filler, a warm opening, a direct ask near the end, and the phrases you never use. Add one before-and-after example. Save it. From then on the model writes in your voice when you ask it to draft an email, because it recognized the task from your description and read your rules.
The same shape works at the other end of the spectrum, where a team uses a skill to enforce how it writes requirements or reviews code. The file is bigger and the rules are stricter, but the mechanism is identical: a description that catches the task, a body that says how the work gets done.
Or have the model draft it for you
If writing the file from scratch sounds like more friction than the task it would save, there is a cheaper way to start. Paste the prompt below into your AI assistant. It will ask the questions a skill needs answered, then draft a SKILL.md you can save and try.
I want to build an Agent Skill so I stop re-explaining the same
task to you every time.
Before writing anything, ask me about it:
1. What is the repeating task, in one or two sentences?
2. What does a good result look like? Show me an example if
you have one, or ask me to paste one.
3. What are the steps you take, including the small judgment
calls you make without thinking about them?
4. What inputs do you start from, and what format do you want
the output in?
5. What should never happen in the output, the things you always
have to fix when someone else does this task?
6. When should this skill trigger? Describe the situations in
plain language, including the words you would actually type
when asking for help with this.
Ask the questions one or two at a time so I can answer without
writing an essay. When you have enough, draft a complete SKILL.md
as a single markdown file I can copy. Include YAML frontmatter
with a name (lowercase, hyphenated) and a description written to
trigger on the situations I described, even if I do not say the
skill's name. In the body, give the instructions in plain
language, include one worked example from my answers, and add a
short checklist the agent can run before finishing the task.
When the draft is ready, ask me to try it on one real example
and tell you what to fix.
When the file comes back, try it on one real instance of the task before you commit to it. Skills get good through a round or two of edits. Expect to revise once you see what the agent does with the first pass.
Where it lives
Where you save the file depends on the tool, and the format stays the same everywhere, which is the entire point of the standard. In the Claude apps you turn skills on in settings and upload your own. In Claude Code, a coding tool that runs in the terminal, skills live in a folder named .claude/skills, and if you commit that folder to a shared project, everyone on the team inherits the same skills the way they inherit any other shared file. Through the API, an endpoint manages them. The same SKILL.md travels across a growing list of tools from different companies, because at the end of 2025 the format became an open standard rather than one vendor's feature, and by early 2026 more than thirty tools had adopted it.
Sharing changes what a skill is worth. Commit one to a shared project and the convention stops living in someone’s head, or in a wiki page nobody opens, and starts living in a file the tools read on their own. The team no longer depends on whoever happened to remember how the work is supposed to be done.
One caution before you install other people’s skills
A skill is instructions the model will follow, which makes a skill from a stranger exactly as trustworthy as a stranger’s instructions. A skill can tell the model to run code or reach for data, and a malicious one can do that in ways its friendly description hides. A security study in early 2026 found that more than a third of the skills published to public registries carried flaws, and dozens carried outright malicious payloads. Apply the rule you would apply to any script you found online. Use skills you wrote, or skills from a source you trust, and read the file before you install it. The format is plain text, which is also its safeguard: you can open any SKILL.md and read exactly what it tells the model to do.
Start with what you repeat
The whole idea is smaller than it sounds. A skill is plain instructions in a plain file, read by the tool when the moment fits, written once instead of every time. Writing one takes no code and no permission. Pick the task you are tired of explaining, write down how you want it done, and hand it over. The next time the task comes up, the work starts where you left off instead of from nothing.
By Joshua McDonald on May 27, 2026.
Exported from Medium on August 26, 2026.
Reader discussion