What are agent skills, really?

What an agent skill actually is

An agent skill is a folder on disk with a file called SKILL.md inside it. That file holds a name, a short description, and instructions written in plain markdown. The agent loads the description at startup, and it reads the instructions only when your request matches that description. Almost everything else about skills follows from those two sentences.

The folder may hold more than the one file. The Agent Skills specification names three optional directories: scripts/ for code the agent runs, references/ for documents it reads when it needs them, and assets/ for templates and data. None of them are required. A folder with nothing in it but a SKILL.md is a complete skill.

restore-drill/
  SKILL.md
  references/retention-policy.md
  scripts/verify_snapshot.sh

The description is the part people underestimate. It is the only text the agent sees before it decides whether to open the skill at all, so it has to say what the skill does and when to use it, in the words a person would really type.

Why a skill costs almost nothing until it is used

This is the argument that makes the format worth understanding, and it is about context, not features. Loading happens in stages, which the specification calls progressive disclosure.

At startup the agent loads the name and description of every installed skill and nothing else. The Agent Skills specification puts that at roughly 100 tokens per skill (published guidance, as of August 2026). Install a dozen skills and you have spent about the context of one long paragraph.

When a request matches a description, the agent reads the body of that one SKILL.md. The spec recommends keeping the body under 5,000 tokens and the file under 500 lines. Files in references/ and scripts/ still cost nothing at this point. A reference file loads only if the instructions send the agent to it. A bundled script is different again: the agent runs it through the shell, so the script's source never enters the context window and only its output does.

Now compare that with the thing people reach for first, which is one enormous prompt. Every line in a system prompt or an always-on instructions file is paid on every request, in every session, whether the task needs it or not, and it competes for attention with the actual question. Ten thousand tokens of standing instructions is a bill you pay even to ask what time it is. A dozen skills cost around 1,200 tokens at rest and expand only for the one task that needs them. That is the whole case for skills, and it is why a small library beats a longer prompt.

One caveat catches people out. Once a skill loads, its body stays in context for the rest of the session, so a long SKILL.md is a recurring cost and not a one time one. Moving detail into references/ is not tidiness. It is the mechanism working as designed.

An agent skill is not a tool call

A tool, also called a function call, is something the model can invoke. The harness sends the model a schema: a name, a description, and the shape of the arguments. The model emits a call, your code runs it, and the result comes back as a message. Tools do things.

A skill executes nothing on its own. The agent reads it, then acts using the tools it already had. The model cannot pass arguments to a skill the way it passes arguments to a tool. What a skill can do is tell the model which tools to use, in what order, and what to check afterwards.

The short version: a tool gives an agent a new ability, and a skill gives it judgment about an ability it already has. If a step must produce an exact, validated result every time, you want a tool or a script. If a step needs the same thinking applied consistently, you want a skill.

An agent skill is not an MCP server

MCP (model context protocol) is a protocol for connecting an agent to an outside system. An MCP server is a process that runs, speaks that protocol, and exposes tools to the agent. It usually needs configuration, credentials, and either a local command or a network endpoint. A skill is a folder with a markdown file in it. There is no process, no port and no protocol.

The context cost differs in the same way. Every tool an MCP server exposes carries a name, a description and an argument schema, and by default those sit in the request for the whole session, used or not. Some clients have started fetching tool schemas on demand, but loading them upfront is still the normal case. A skill at rest is one line of text.

The two are complements, and the strongest setups run both. The MCP server provides the access. The skill provides the procedure: which of those tools to call for your team's real workflow, in what order, and what a good result looks like. If you host your own, running MCP servers on a VPS covers that side of it.

An agent skill is not a system prompt or an AGENTS.md

Both are instructions in markdown, so this confusion is fair. The difference is when they load. AGENTS.md, CLAUDE.md and the system prompt are always on. A skill is on demand.

The test is one question: would ignoring this paragraph be wrong on a task that has nothing to do with it? House style, the build command and the branch naming rule apply to every task, so they belong in the always-on file, where being loaded every time is the point. The release checklist you run twice a month does not apply to every task, so it belongs in a skill. When a section of your always-on file has grown into a numbered procedure, that is the signal to move it.

Those files have conventions of their own worth getting right. See what belongs in AGENTS.md and what belongs in the human file and a design.md that explains the shape of a codebase for the two we use.

What a minimal skill looks like

In Claude Code, personal skills live in ~/.claude/skills/<name>/SKILL.md and apply to all your projects. Project skills live in .claude/skills/<name>/SKILL.md and get committed to git, so every person and every agent working in that repository has them. GitHub Copilot and VS Code read workspace skills from .github/skills/ instead. The file inside is the same file.

mkdir -p ~/.claude/skills/restore-drill

---
name: restore-drill
description: Run a restic restore drill and report what was recovered. Use when the user asks to test backups, verify a restore, or check that a snapshot is readable.
---

# Restore drill

1. Run `restic snapshots` and pick the newest snapshot for the host in question.
2. Restore it into a scratch directory under `/tmp`, never over live data.
3. Compare the restored file count and total size against the snapshot summary.
4. Report the snapshot ID and anything that failed to restore.

If `restic snapshots` prints `Fatal: unable to open config file`, the repository path or the password is wrong. Stop and report that instead of guessing.

That is a complete skill. The directory name becomes the command you type, so this one is /restore-drill. In Claude Code the /skills menu lists what is installed, which is the quickest way to confirm the file was picked up. If it is missing from that menu, a name is wrong: the file must be called SKILL.md, and the directory name must be lowercase letters, digits and single hyphens. The same drill written as a procedure your agent can rerun is a natural companion to scheduled restic backups on a VPS, where the backup running is not the same as the backup restoring.

When a skill should be a script instead

Any step with one correct answer every time should be a script, with the skill reduced to a few lines that say when to run it and how to read the output. There are two reasons, and both are practical.

First, a script's source never enters the context window. A 300 line parser costs you its output and nothing more, while the same logic written out as markdown instructions costs its full length every time the skill loads.

Second, a script gives the same answer twice. A model asked to re-derive the same log parsing rule on every run will get it slightly different on a bad day, and you will not notice until two numbers disagree.

So split the work by kind. "Parse the CSV and print every row where the total does not match the line items" is a script. "Look at the rows the script printed and explain which ones look like a data entry mistake" is a skill instruction. Keeping judgment in markdown and determinism in code is the same discipline as building a loop an agent can run without you watching.

Why does my skill never trigger?

Because its description says what the skill does and never says when to use it. That one line is all the agent has to match your request against. "Helps with database work" matches nothing in particular. "Runs a schema migration against the staging database. Use when the user asks to migrate a table, add a column, or change a schema" contains the words a person actually types, so it fires.

The opposite failure is the skill that triggers constantly. A description such as "Use for any code changes in this repository" matches everything, so the body loads on every task and then sits in context for the rest of the session. Narrow the description to the case you meant. In Claude Code you can also set disable-model-invocation: true in the frontmatter, which stops automatic loading and keeps the skill available when you type its name.

The third failure is the skill that duplicates a tool. Instructions telling the agent to curl an API that its MCP server already exposes, or to grep through files when the harness has a search tool, give you a slower path plus two sets of instructions that can disagree. Delete the duplicate and describe the intent instead.

Do not guess which of the three you have. Run the same prompt twice in a fresh session, once with the skill available and once with it switched off, then compare the answers. The fresh session matters, because the session where you wrote the skill already contains everything the skill says, which hides gaps in the written version. Anthropic's skill-creator plugin automates that comparison inside Claude Code, including generating prompts that should and should not fire the skill and measuring how often each one does.

Is this one vendor's format or a standard?

Anthropic published the format in late 2025, then released it as an open standard hosted at agentskills.io. As of August 2026 that specification defines the required name and description fields, the optional license, compatibility, metadata and allowed-tools fields, the three optional directories, and the staged loading behaviour. It also ships a reference validator, so skills-ref validate ./my-skill checks a folder against the spec before you share it.

The client list is the real signal. The same folder is read by Claude Code, Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands and opencode, among others. Microsoft publishes its own skills in the format at github.com/microsoft/skills, and ships a desktop tool called Skill Recorder that watches you do a task once, reconstructs it as an intent plus ordered steps, and writes the result out as a skill. A vendor building a recorder whose output format belongs to somebody else's specification is a good sign that the format has stopped being one product's feature.

What to write first

Do not plan a library. Wait until you catch yourself pasting the same instructions into a chat for the third time, then move that text into a SKILL.md and delete the paste. Repetition you have already felt is the only reliable trigger for a skill worth keeping. A search procedure is a good first one, and a search skill backed by your own SearXNG instance shows the shape.

Two habits keep the library healthy. Read every skill you did not write before you install it, scripts included, because a skill is instructions your agent will follow and code it may run: treat it like installing software from a stranger. And keep credentials out of the folder, since a skill is a text file that gets committed and shared. Keeping secrets away from your agents covers where those values belong instead, and the road map for learning agents this year puts skills in order with the rest of the setup.

FAQ

What is the difference between an agent skill and an MCP server?

An MCP (model context protocol) server is a running process that exposes tools to an agent over a protocol, so it needs configuration and credentials, and its tool definitions normally occupy context for the whole session whether they are used or not. An agent skill is a folder holding a SKILL.md file, with no process and no protocol, and it costs around 100 tokens until the agent decides to read it. Use an MCP server to give an agent access to a system. Use a skill to tell the agent the procedure for using that access well. Many setups run both.

Do agent skills only work with Claude Code?

No. Anthropic developed the format and then released it as an open standard at agentskills.io, and the same folder is read by Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands and other clients. What differs is where each client looks and which extra frontmatter fields it understands. Claude Code reads ~/.claude/skills/ and .claude/skills/, while GitHub Copilot and VS Code read .github/skills/ in the repository. The SKILL.md file itself moves between them unchanged.

How many skills can I install before it slows things down?

The constraint is the startup budget rather than a count. Each installed skill contributes its name and description, roughly 100 tokens by the specification's published guidance, so thirty skills cost about 3,000 tokens before any of them is used. What degrades first is matching, not speed: many skills with overlapping descriptions make it harder for the model to pick the right one. Write descriptions that do not overlap, and delete the skills you stopped using.

Should this instruction go in a skill or in AGENTS.md?

Ask whether it applies to every task in the repository. Build commands, house style and naming rules apply to all of them, so they belong in the always-on file, where loading every time is the point. A procedure you run occasionally, such as a release checklist or a restore drill, should be a skill, so it costs nothing on the tasks that never need it. A section of AGENTS.md that has grown into numbered steps is usually a skill waiting to be moved.