AI Stack Library · Tools and MCP
What are agent skills, and how to write one your agent will use
Agent skills are folders that hold a written procedure: a SKILL.md file with a name and a short description at the top and the steps below, plus any references or scripts the job needs. The agent reads only the description until a request matches it, then loads the rest. Write one for any job you have explained to an agent twice, and keep it in your own files, because the format is an open standard that many agents read.
| If you are | Start with |
|---|---|
| An owner who keeps re-explaining the same task | A dedicated always-on machine, then one skill for that task, written from the last time it went right |
| A service business with a fixed way of quoting or taking on clients | A dedicated always-on machine, then a skill holding the steps, a pointer to the price sheet and the point where it stops for approval |
| A developer | A dedicated always-on machine, then skills kept in a git repository, so every change is reviewed and can be undone |
| A creator with a house style | A dedicated always-on machine, then a skill for the script and title steps, with your voice notes as reference files |
A skill is the explanation you stop repeating
Everyone who works with an agent ends up typing the same paragraph twice. How to quote a fence job. Which folder the invoices go in. Who signs off before a customer hears a price. A skill is that paragraph, written down once, in a place the agent looks.
On disk it is a folder. Inside is a file called SKILL.md: a name and a description at the top, then the steps. Longer material, such as a price sheet or a style guide, sits beside it as reference files, and anything mechanical can be a script the agent runs instead of working it out again.
Anthropic developed the format and released it as an open standard, Agent Skills. Its specification puts it simply: at its core, a skill is a folder containing a SKILL.md file.
A made-up skill for quoting a fence job, with six labelled parts: the folder name, the name, a description that says when to use it, four short steps ending in an approval stop, two reference files, and what done looks like.
- Folder
- quote-a-fence-job/
- Name
- quote-a-fence-job
- Description
- Use when a customer asks what a fence will cost. Drafts a quote from the price sheet and stops for the owner's approval before anything is sent.
- Steps
- 1. Ask for length, height and material if any are missing. 2. Price it from price-sheet.md. 3. Fill in quote-template.md. 4. Stop and ask the owner to approve.
- Reference files
- price-sheet.md, quote-template.md
- Done means
- A draft quote saved for review. Nothing sent.
Example data, made up to show the idea. Not a measurement.
How an agent decides to load one
The description does the choosing. Anthropic's docs say that until a skill is triggered, only its name and description take up room in the agent's context. When a request matches a description, the agent loads that skill's instructions and follows them. The rest stay closed.
So write the description for the moment of need, not as a label. 'Pricing' tells the agent nothing. 'Use when a customer asks what a fence will cost' tells it exactly when. The open standard says the same: the description says what the skill does and when to use it.
Four steps. A request arrives. The agent compares it with every skill's name and description, and nothing else. One description matches, and that skill's steps and references load. The steps run while the other skills stay closed.
- A request arrives
- The agent reads every skill's descriptionnames and descriptions only
- One description matchesthat skill's steps and references load
- The steps runthe other skills stay closed
Skills, rules and memory: three different files
Three kinds of file shape what an agent does, and they are easy to mix up. A rules file says what must always be true. Memory holds facts about your business. A skill holds a procedure, and it loads only when the job calls for it.
Put a fact in a skill and it goes stale in two places at once. Put a procedure in the rules file and every session pays to read it, including the hundred sessions that will never quote a fence.
A three-row table. The rules file holds what must always be true and is read at the start of every session. Memory holds facts about the business and is read when a question needs them. A skill holds how to do one job, step by step, and is read when a request matches its description.
| File | What it holds | When the agent reads it | Example |
|---|---|---|---|
| Rules file | What must always be true | At the start of every session | Never send anything to a customer without approval |
| Memory | Facts about your business | When a question needs them | This client prefers email to phone calls |
| Skill | How to do one job, step by step | When a request matches its description | How to quote a fence job |
Skills and tools are not the same thing
A tool lets the agent do something: read a calendar, write to a CRM, run a command. Tools usually arrive through MCP servers. A skill tells the agent how to do a job well with the tools it already has: which fields to fill, in what order, and where to stop and ask.
Connect a CRM and the agent can create a contact. Give it a skill and it creates the contact the way your office does, with the lead source filled in and no duplicate.
Write it from the last time it went right
Do not write a skill from how the job ought to go. Write it from a real run, the evening after it went right, while you still remember the step you nearly skipped.
- A description that names the moment: the words a person uses when they need this job done.
- The inputs it needs, and what to ask for when one is missing.
- The steps, in order, short enough to read in a minute.
- The approval point, where it stops and waits for a person.
- What done looks like, so the agent knows when to stop.
- What usually goes wrong, and what to do then.
Never write a password or key into a skill. Write the name of the key and where the agent should ask for it.
Keep each skill small
One job per skill. If the description needs the word 'and' twice, it is two skills.
Move long material into reference files the skill points to, so it loads only when a step needs it. Turn anything mechanical, such as renaming files or totalling a quote, into a script, so the agent runs it the same way every time instead of improvising it.
The open specification sets the outer limits: a name of up to 64 characters, in lowercase letters, numbers and hyphens, and a description of up to 1,024 characters. Anthropic's own version adds that a name may not contain the words anthropic or claude.
Test it in a fresh session
A skill that works in the session where you wrote it proves little, because that session already knows what you meant. Open a new one and try it the way a colleague would ask.
A five-item checklist: it loads when you ask in your own words, it loads when you ask in different words, it stays closed for a nearby but different request, it stops at the approval point, and its output matches what done looks like.
- It loads when you ask for the job in your own words
- It loads when you ask in different words, the way a colleague would
- It stays closed when you ask for something nearby but different
- It stops at the approval point and waits
- Its output matches what done looks like
Which agents read skills
Because the format is shared, one skill folder can serve several agents. The Agent Skills site lists the products that support the format, and on 2026-10-23 that list included Claude Code, ChatGPT and Codex, GitHub Copilot, VS Code, Cursor and Gemini CLI.
Each looks in its own places. Claude Code reads personal skills from a skills folder in your home directory and project skills from the project. Codex scans a .agents/skills folder in the repository and in your home directory. GitHub Copilot reads project skills from .github/skills, .claude/skills or .agents/skills, and personal skills from your home directory.
Anthropic's apps read skills too, in Claude Code, through the Claude API and in claude.ai settings, but its docs note that custom skills do not sync across those surfaces.
One home for your skills
Copies drift. A skill pasted into three agents' folders becomes three slightly different skills before long, and nobody can say which one is right.
Keep one master folder. Make copies elsewhere only through a sync you control, never by hand, and for a team keep the master in a git repository so every change is reviewed and can be undone.
Two panels. Copies made by hand: three folders hold three versions, a fix lands in one and not the others, and nobody knows which is current. One master with synced copies: one folder is the source, copies are made by a sync and never by hand, and every change is reviewed and can be undone.
Copies made by hand
- Three folders, three versions
- A fix lands in one and not the others
- Nobody knows which is current
One master, synced copies
- One folder is the source
- Copies are made by a sync, never by hand
- Every change is reviewed and can be undone
Own them
Skills kept as files in your own folders travel with you when you change agents. Procedures kept inside one vendor's builder may not.
OpenAI has scheduled custom GPTs to retire on Dec 11, 2026, and its migration guide says migrating turns a GPT's instructions into a skill. A procedure already written as a skill folder has nothing to migrate. Our guide to renting or owning each layer of the stack covers the rest of that choice.
Read every file before you install someone else's
A skill can carry scripts, and a script runs with whatever access the agent has. Anthropic's docs say to use skills only from trusted sources, those you wrote yourself or got from Anthropic, and to audit anything else thoroughly before use. Claude Code's docs add that a skill can grant itself broad tool access, so review the tools a skill allows before you run an agent in a project that contains it.
Even Anthropic's public skills repository says its skills are for demonstration and education, and to test them in your own setup before relying on them for anything critical.
What goes wrong
- A description written as a label, so the skill never loads.
- One skill that tries to do five jobs and does none of them reliably.
- Facts copied into a skill that go stale while the memory folder stays current.
- Three copies of the same skill, each fixed in a different place.
- A downloaded skill installed without anyone reading the script inside it.
Questions
Are agent skills the same as tools?
No. A tool lets an agent act, such as reading a calendar or writing to a CRM. A skill is a written procedure for doing a job well with the tools it has: which steps, in what order, and where to stop for a person.
Which AI agents can use SKILL.md skills?
Agent Skills is an open standard. On 2026-10-23 its list of supporting products included Claude Code, ChatGPT and Codex, GitHub Copilot, VS Code, Cursor and Gemini CLI, among others. Each reads skills from its own folders, so check where yours looks.
Do skills replace a rules file?
No. The rules file holds what must be true in every session. A skill holds one procedure and loads only when a job matches it. Most setups need both, plus a memory folder for facts.
Terms on this page
Sources
- Agent Skills (open standard), checked 2026-10-23
- Agent Skills: Specification, checked 2026-10-23
- Agent Skills: Clients, checked 2026-10-23
- Claude Platform docs: Agent Skills overview, checked 2026-10-23
- Claude Code docs: Skills, checked 2026-10-23
- anthropics/skills on GitHub, checked 2026-10-23
- Codex docs: Build skills, checked 2026-10-23
- GitHub Docs: About agent skills, checked 2026-10-23
- OpenAI Help Center: Custom GPT retirement and migration FAQ, checked 2026-10-23
- ChatGPT docs: Migrate custom GPTs, checked 2026-10-23