A skill is a set of instructions for a task you want an AI to remember. It is a folder containing one file, called SKILL.md. It is a memo to your new research assistant.
Your skill includes triggers for when to use the skill. If you are my sous chef and I say hard boil these eggs (the trigger), you open your skill (an instruction file you created in culinary school) on how to do that without further instructions. Only the name of the skill and that trigger stay loaded (about 100 tokens per skill). The instructions themselves are read only once a request matches. That is why you can keep fifty skills on hand without slowing anything down or crowding out the actual work. A prompt you paste every time (or even a long system prompt) is in the way every time. A skill is only there when it is needed.
This is no longer a Claude-only feature. Anthropic released the format as an open standard in December 2025, and roughly forty tools now run the same SKILL.md file unchanged — Claude, Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, VS Code and others. A skill you write this year should still run next year in whatever you have switched to. That portability is the strongest practical argument for writing one.
- The open standard and specification: agentskills.io
- How skills work, in detail: Agent Skills overview
- Writing good ones: Skill authoring best practices
- Setting them up in Claude: Creating custom Skills
Skills sit at the end of the workflow on the AI Research Workflow page: once you have refined a set of rules for something you will do again, this is how you stop re-explaining it.
I almost always ask Claude to write the skill for me. So after I have worked through a project with a series of prompts, I say, take what you have learned about how I want this done and turn it into a skill. Sometimes I read and edit the skill, but mostly I just try it on a new example to see if it works. (See below.)
Skills, prompts, project instructions and bots sometimes get confused.
| Use a… | When | Loads |
|---|---|---|
| Prompt | One task, one time. You are still working out what you want. | Now, by you |
| System prompt | Standing rules true of everything you do, in every project: how you want to be addressed, argued with, and corrected; your standing preferences about evidence, length and tone. It goes in your general settings. | Every conversation, always |
| Project instructions | Standing rules true of everything in this body of work: your evidence standards, citation style, what counts as a source in your field. | Every conversation in that project |
| Skill | A recurring task with rules you keep re-explaining. Grading with your rubric. Building a particular kind of document. Applying your codebook. | Only when that task comes up |
| Custom bot / GPT / Gem | Someone else — a student, a colleague — will use it, in a chat window, without you there. | Whenever they open it |
If it is true of EVERYTHING you do, it is a system prompt (and it goes in your general settings). If it is only true for a specific project (writing a book, updating your website) it is project instructions. If you find yourself re-explaining it, it is a skill. If a student will use it, it is a bot.
When to Write One
Three conditions. You need all three.
- You have done the task at least twice. Preferably badly the first time.
- You have opinions about what “done right” means that the AI does not share by default. If its default output is fine, you do not need a skill; you need a sentence.
- You could tell whether the output was right. This is the one people skip.
If the third condition fails, do not write the skill. You would be automating a judgment you have not yet made, and the result is worse than doing it by hand — because now the judgment is invisible.
Do not write a skill for: anything you will do once; anything where the right answer genuinely changes each time; anything that depends on current information, since a skill is frozen text and does not know what happened last month. And do not write one before doing the task well by hand at least once. A good skill is the transcript of a success, not a plan for one.
Examples:
- Evaluate the credibility of sources in this way…
- Apply my rubric criterion by criterion; feedback first, grade last; coach by question, not correction.
- Extract a text’s thesis, premises and hidden assumptions first; steelman before critiquing.
- Sort evidence in this way…
- Apply my codebook to interviews or field notes in this way…
How to Write One
Do not sit down to write a skill. Sit down to do the task, and let the skill fall out of it.
- Do the task with the AI. Argue with it. Correct it. Push back until you get something you would put your name on. Pay attention to whatever you had to say more than once.
- Then ask it to write the skill (prompt below).
- Run it cold in a brand-new chat. It will fail somewhere. That failure is the most valuable information you will get. Fix that one thing and run it cold again. Two or three rounds is usually enough.
SKILL PROMPT: Write a skill that would have produced this result without me having to correct you. Include the specific mistakes you made along the way and what fixed them. Write the description field so that it triggers on the words I would actually use, not the words you would use. Keep it under two pages; put anything longer in a separate reference file.
Show your style — do not describe it
It is VERY hard to describe the format you want. Show the AI examples instead, and make it do the extraction.
SKILLS PROMPT: Here are three finished documents of the kind I want. Read them and write down every formatting rule you can infer: fonts, sizes, colors, spacing, how images are placed, how citations are punctuated, what always appears first and last, what never appears at all. Where you see me doing something inconsistently, tell me and ask which version I meant. Then write those rules into the skill as a table, one row per element, so they can be checked afterwards.
Two refinements make the difference between a skill that holds and one that rots:
- Make it re-ground itself. Add a standing instruction: “Before you start, find the most recently modified example of this document in my folder and read it. I edit these by hand, and my newest edit is the current house style.” Your style drifts. The skill should follow it rather than freeze it.
- Write rules that can be checked. “Nothing smaller than 9 point” survives a handoff. “Keep it legible” does not. If a rule cannot be verified by a script or by eye in ten seconds, it will drift — and you will not notice until someone in your audience does.
The description field is the part people get wrong
The description is not a summary — it is the trigger. It is the only part of your skill the AI sees before deciding whether to open it. It must say what the skill does and when to use it, phrased in the words you would actually type. A description that says “handles document formatting” will fire on everything or nothing. One that says “use when I say make the citations doc, convert this deck, or the doc doesn’t match the slides anymore” will fire when you want it.
An Example: turning a deck into a citations document
Below is a real, working skill, generalised so that anyone can use it. It solves a specific problem. Every time I give a presentation, people want the slides, but they also want the citations. I don’t want to clutter up my slides so I put them in the notes, which don’t transfer when you export a pdf. For years, I’ve created a slides and citations doc for every presentation. This is a nightmare of version control.
Now I’ve taught Claude how to do this. I asked it to turn one of my presentation decks into a word doc using the images of the slides but adding the citations and active links next to each slide. I then edited the word doc Claude produced and asked Claude to review my changes. I did this with two more decks and by the third, it was getting it mostly right.
This skill turns a .pptx into a Word document with every slide as an image, its citations and links beside it, and every link or prompt written out in full so it can be pasted straight into a chat window. It runs out of the box — but it will produce my document, not yours, until you change the parts marked CUSTOMIZE: the fonts and colors, where your files live, your discipline’s evidence ladder, and the standing citation flags for the papers in your field that need consistent handling. The first section of the file walks through those eight items. Do not edit them by hand. Give the AI an example (or three) of your own documents and use the extraction prompt above; it will do a better job on your style than you will.
Two things worth noticing about how it is written, because they generalise to any skill you make:
- It states its own failure modes. Renumbering after you insert a slide, so the document silently shows the wrong image; a rendering library substituting a font and overflowing every slide. Those cost hours to discover and one line to write down. The mistakes are the most valuable content in any skill.
- It ends with a test. A short script that counts font sizes and checks that no image is anchored inline. Rules that cannot be checked are wishes.
Download: slides-and-citations-SKILL.txt · slides-and-citations-SKILL.docx
This is really just so you can see a skill. The best way to make this is to start with the work. BUT if you must, save the .txt version as a file called SKILL.md inside a folder named slides-and-citations. In Claude Code, drop that folder into ~/.claude/skills/. On claude.ai, zip the folder and upload it under Settings. Other tools differ slightly — agentskills.io lists them. The Word version is for reading; the text version is the one that runs.
Limits
A skill encodes your errors as faithfully as your expertise. This is the real risk and it is not small. Anything wrong in the file is now wrong every single time, applied consistently, at speed — and because the output looks right, you stop checking. A rule you wrote in March on a false assumption will still be running in November. Date the parts that can go stale, and re-read the whole file periodically.
A skill does not verify itself. Nothing in the format checks that its instructions are correct, current, or even coherent. Build a verification step into the skill, and make the AI report what it could not confirm.
Treat an unfamiliar skill like software you are installing. A skill is executable instruction with access to whatever your AI has access to. Anthropic’s own documentation is blunt about this: use skills only from sources you trust, and audit anything you did not write — particularly anything that fetches from an external URL, since fetched content can carry instructions of its own. This is a genuine attack surface, not a formality.
Skills do not sync across tools. One uploaded to claude.ai is not available in the API or in Claude Code; each surface is separate. Keep your master copy in a folder you control, not inside any one product.