Agent Skills

Suppose you use an AI agent to check supplier invoices. Every time you start a new conversation, you type the same rules again: "Flag any total that is more than 1% off the purchase order. Use the supplier's name, not the trading name." The rules never change, but the agent does not know them until you type them.

An agent skill removes the retyping. You write the rules once, save them in a file, and put the file where the agent looks. From then on the agent picks the file up by itself when a task needs it.

Skills are the second main way to give an AI agent abilities it did not come with. The first is the Model Context Protocol, which connects an agent to outside systems through tools. A skill adds something different: written know-how about how a job should be done.

After this lesson you can read a skill file, explain how an agent decides which skill to open, and write a description that makes a skill get picked at the right time.

1. A skill is a text file you can open

A skill is not a program. It is a text file written in Markdown. Markdown is plain text with a little formatting: a line that starts with ## is a heading, and a line that starts with 1. is a numbered step. You can open the file in any text editor and read it.

Here is a complete skill for the invoice job. PO stands for purchase order, the document a company sends a supplier to order goods at an agreed price.

invoice-triage/SKILL.md

---
name: invoice-triage
description: Sort incoming invoices and flag
  any total that does not match its PO.
---

<h2 id="steps">Steps</h2>

1. Pull out supplier, number, total.
2. Match it to a PO in purchase-orders/.
3. Flag anything more than 1% off.

The file has two parts, and the two lines of three hyphens (---) mark the border between them.

• Above the second --- is the metadata. Metadata means information about the file: here, the name of the skill and a description of it. This block at the top of a file is also called frontmatter.
• Below the second --- are the instructions. These are the steps you want the agent to follow, written in ordinary sentences.

Nothing has to be compiled, which means nothing has to be translated into a form a computer can run. Nothing has to be installed either. The instructions are read by the model as text, the same way it reads a message you type.

2. The folder is the skill

A skill has to be stored in a fixed shape so that an agent can find it. That shape is a folder.

invoice-triage/          the folder name is the skill name
    SKILL.md             required: metadata plus the instructions
    references/          optional: extra detail
    scripts/             optional: code
    assets/              optional: templates

Three things about this layout matter.

1. The folder name is the skill name. A skill called invoice-triage lives in a folder called invoice-triage.
2. SKILL.md is required. The file always has this name, so an agent knows what to look for in every folder.
3. Three kinds of extra folders are optional. references/ holds longer background documents, such as a full list of supplier rules. scripts/ holds small programs the agent can run. assets/ holds templates and other files to copy from. The instructions in SKILL.md can point at any of these.

The folder and the fixed file name are what make a skill discoverable. An agent does not need to be told about each skill. It scans a folder, and every subfolder that contains a SKILL.md is a skill.

3. A prompt written once and reused

The shortest way to describe a skill: it is a prompt that you write one time and never type again, stored where the agent finds it without your help.

The knowledge is yours in both cases. What changes is who has to remember it.

Without a skill, a rule you forget to type is a rule the agent does not follow.

An everyday picture: a new employee gets a written procedure for handling invoices instead of being told the steps aloud every morning. The skill is the written procedure. The picture stops being accurate at one point. An employee learns the procedure after a few days and no longer needs the paper. A model keeps no memory between conversations, so the file has to be read again each time.

4. The application adds the skill to the request

You never paste a skill into the chat. The agent software does that work.

flowchart LR
    A["SKILL.md<br/>stored in a folder"] --> B["The agent<br/>reads the file<br/>and adds your prompt"]
    B --> C["The model<br/>receives both<br/>as one prompt"]

The diagram reads from left to right. The file sits in a folder on disk. The agent software reads it and puts its text together with the message you typed. The model then receives one combined input.

This is the same mechanism as every other part of a model's context. The model has no separate channel for skills. A skill is text that the application places into the request, next to system instructions, tool definitions, and your message.

5. The two metadata fields

A stored prompt is only half of what a skill is. The other half is the metadata, and it is the half the agent reads first.

The metadata is also what makes skills a standard. A standard is an agreed format that different products follow. The Agent Skills format was first published by the company Anthropic and is now an open format that several agent products support at the time of writing. Because every skill carries the same two fields in the same place, any agent that supports the format can use a skill written by anyone.

Here is the metadata of the invoice skill again, with a fuller description:

---
name: invoice-triage
description: Sort incoming invoices, check
  totals against the PO, and flag mismatches.
  Use when the user mentions invoices,
  billing or accounts payable.
---

Every skill must carry these two fields.

The description is written for a reader who has not opened the file. At the moment the model reads the description, it has not seen the instructions below it. The description alone has to tell the model whether this skill fits the request.

6. A skill is loaded in stages

An agent may have dozens of skills. If the full text of every skill went into every request, most of the context window would be filled with instructions that have nothing to do with the current task. So skills are loaded in stages: the short descriptions first, then the full file of the one skill that fits, and then extra files only if they are needed.

flowchart TB
    A["Always in the context:<br/>the description of every skill<br/>(a line or two each)"] --> B["Your request arrives.<br/>The model compares it<br/>with those descriptions"]
    B --> C["The one skill that matches<br/>is opened in full"]
    C --> D["Extra files are opened<br/>only if the instructions<br/>call for them"]

1. Every description is always loaded. For each skill, the agent keeps its name and description in the context the whole time. That is a line or two per skill.
2. The model matches your request against the descriptions. When your message arrives, the model reads it together with the short descriptions and judges which skill, if any, fits.
3. One file is opened in full. Only the skill that matched has its whole SKILL.md loaded, and only at that moment.
4. Extra files are opened if needed. A reference document or a script in the skill folder is read or run only when the instructions say so.

This approach is often called progressive disclosure, which means showing a little first and more only when it is needed.

A small worked case with made-up numbers shows the saving. Suppose an agent has 20 skills. Each description is about 50 tokens, and each full skill file is about 1,500 tokens.

all 20 skills loaded in full:   20 x 1,500 = 30,000 tokens in every request

staged loading:
  20 descriptions:              20 x 50    =  1,000 tokens in every request
  one matching skill in full:               + 1,500 tokens, only when it matches
                                            -------
                                              2,500 tokens

Staged loading uses 2,500 tokens where loading everything would use 30,000. The other 27,500 tokens stay free for the conversation and the actual work.

7. An example: four skills, one question

Suppose one agent has four skills. Two are for bookkeeping and two are for software development.

Before you ask anything, only the four descriptions are loaded. Then you ask:

Any invoices this week that don't match their PO?

The question is about one half of what this agent can do. The model compares it with the four descriptions. The words "invoices" and "PO" fit the description of invoice-triage, so the agent opens that one file in full. The other three stay shut.

Loading all four would spend context on three skills that cannot help with this question. The instructions of the two software-development skills never reach the model, so they use no tokens beyond their short descriptions.

The expense-policy skill also stays shut, even though it belongs to bookkeeping. The match is made per skill, not per area.

8. Writing a description that gets matched

The description is the only part of a skill that the model can weigh before it decides to open the skill. This is why the standard requires it, and why its wording decides whether the skill is ever used.

The criterion is: a description should state what the skill does and contain the words a person would type when they need it. People who need the invoice skill will write "invoice", "billing", or "accounts payable". Those words belong in the description.

A vague description has a second cost. If it matches many requests, the skill is opened when it is not needed, and its full text takes up context for nothing.

9. Where skill folders go

Each agent product looks for skills in its own set of folders. The shape is the same everywhere, but the exact paths differ from product to product.

a folder the agent scans      per project or per user
    invoice-triage/           one folder per skill
        SKILL.md              found, described, and used when the task fits

There are usually two places:

• Per project. A skills folder inside one project. The skills apply only when the agent works in that project.
• Per user. A skills folder in your own user account. The skills apply to everything you do with that agent.

The exact folder names are listed in the documentation of the agent you use, so check there.

Once a skill folder is in the right place, the agent discovers the skill by scanning the folder, reads its description into the context, and activates it when a task fits. Activating a skill means opening its full instructions.

Skills are written by you or your team, so they tell the agent how you want the work done: your tolerance of 1%, your naming rule for suppliers, your folder of purchase orders. A general model cannot know these things from training.

Interview points

• An agent skill is a folder that contains a required SKILL.md file and optional references/, scripts/, and assets/ folders. The folder name is the skill name.
• SKILL.md is Markdown. The frontmatter between the two --- lines is metadata, and everything below it is the instructions. Nothing is compiled or installed.
• Skills and MCP are the two main ways to extend an agent. MCP connects the agent to outside systems through tools, and a skill supplies written instructions for how to do a job.
• A skill behaves like a prompt that is written once and attached by the application, so the user does not retype it in every conversation.
• The two required metadata fields are name, which matches the folder name, and description, which states what the skill does and when to use it.
• Skills load in stages. All descriptions are always in the context, the model matches the request against them, the matching skill's file is loaded in full, and extra files are opened only if the instructions call for them.
• Staged loading keeps unrelated skills out of the context window, so an agent can have many skills at the cost of a line or two each.
• The description is the only part the model sees before choosing a skill. A vague description matches too much, and a description that only repeats the name gives no signal about when to use it.
• A good description states the function and includes the words that a real request would contain.
• Agents scan specific folders for skills, per project or per user. The layout is shared, and the paths depend on the agent.

Summary

• A skill is a folder with a SKILL.md file.
• SKILL.md has metadata (name and description) on top and instructions below.
• The folder name and the name field are the same.
• The application adds the skill to the request. The user does not paste it.
• Only descriptions are always loaded. The full file is loaded for the skill that matches.
• Extra files in references/, scripts/, and assets/ are opened on demand.
• The wording of the description decides whether the skill is used.
• Skill folder locations differ between agents and are listed in each agent's documentation.