Agent Skills

An AI agent with tools can act, but tools alone don't tell it how your team does a job. An agent skill is a small, reusable guide that teaches the agent the steps, rules and traps for one kind of task, and it loads only when that task comes up.

Tools act, skills teach

A tool is a single capability the agent can call: run a terminal command, open a web page, send an API request, read a file. Tools answer 'what can the agent do?'. They say nothing about when to use them, in what order, or what 'done' looks like.

Ask an agent that only has tools to 'open a PR for the docs change' and it has to guess the rest. Which branch? Does the changelog need a line? Should the tests run first? Is there a PR template? A capable model makes reasonable guesses, but reasonable guesses vary from run to run and rarely match your team's actual process. That is where the mess comes from: wrong steps, steps in the wrong order, and a lot of improvising.

A skill fills that gap. It is written knowledge about how to do one particular job: which tools to reach for, the steps to follow, the rules that apply and the mistakes to avoid. The tools stay the same; the skill tells the agent how to combine them. If you've seen how the Model Context Protocol connects agents to tools (MCP vs API), skills sit one layer above that. MCP gives the agent new things it can do, and a skill teaches it a workflow that uses them.

What a skill looks like

In the Agent Skills format, a skill is a folder containing a file called SKILL.md. The file has two parts:

• Frontmatter: a short block of YAML at the top with a name and a description. Both are required. The name is lowercase with hyphens, such as release-notes, and matches the folder's name.
• Body: plain Markdown instructions underneath. There's no fixed format, but most skills have numbered steps, a few rules and an example or two.

The folder can also hold anything the instructions refer to: a scripts/ folder of code the agent can run, references/ for longer documentation, and assets/ such as templates.

The format started at Anthropic for Claude and is now published as an open specification, so the same folder can work in any agent tool that supports it. Where the folder lives depends on the tool. Claude Code, for example, reads a project's skills from .claude/skills/.

How the agent picks the right skill

An agent might have dozens of skills installed. Loading all of them into its context at the start of every conversation would waste space and bury the instructions that matter. So skills load in stages, a pattern called progressive disclosure:

1. At startup, only the name and description. The agent reads the frontmatter of every installed skill, roughly a hundred tokens each. That is just enough to know 'this is the release skill' and 'this is the API skill'.
2. When a task matches, the full SKILL.md. If a request fits a skill's description, the agent opens the whole file and follows it.
3. Only if needed, the extra files. A reference document or template is read when a step calls for it. A script can be run without its source ever being loaded: only its output uses context.

This is why the description does so much work. It is the only part of the skill the agent sees when deciding whether to use it. A vague description means the skill never loads, or loads for the wrong tasks.

The payoff is that you can install many skills cheaply. Each one waits until its moment, then brings the right workflow at the right time.

A worked example: a release skill

Say your team releases a library by hand, and the agent keeps skipping steps. Here is a small skill for it, saved as releasing-the-library/SKILL.md:

---
name: releasing-the-library
description: Cuts a new release of the
  library. Use when asked to release,
  publish or tag a new version.
---
 
## Steps
 
1. Check the working tree is clean and
   you are on main.
2. Run the tests. Stop if any fail.
3. Work out the version bump from the
   commits since the last tag.
4. Add a CHANGELOG.md entry using
   assets/changelog-template.md.
5. Run scripts/bump_version.py with
   the new version.
6. Commit, then open a PR.
7. Tag vX.Y.Z only after the PR merges.
 
## Rules
 
- A breaking change is a major bump.
- Never edit version numbers by hand.

Now, when someone asks 'can you release 2.4?', the agent sees that the request matches the description, opens the skill and follows it. The tests run before anything else, the changelog entry uses your template, the script makes the fiddly version edit the same way every time, and the rule about tags prevents the most expensive mistake. None of that needed a new tool: the terminal and Git were already there. The skill is what turned them into a dependable process.

More than a saved prompt

A skill can look like a prompt saved for later. The difference is in what it carries and how it gets used:

• Steps, so the order is fixed rather than improvised.
• Rules and guardrails: what must always or never happen.
• Examples of good output, which often teach style better than a description of it.
• Templates, so a changelog entry or a PR description comes out the same every time.
• Scripts, for any step that must be exact. Running a tested script is more reliable than asking the model to write the same code afresh.

And unlike a prompt you paste in, a skill is picked up by the agent itself when the task fits. It can be checked into a repository, reviewed like code and shared across a team, so everyone's agent follows the same process. Less guessing means more repeatable results.

Writing a good description

Because the description decides when a skill loads, write it for the agent that is choosing between skills:

• Say what the skill does and when to use it, using the words a person would actually type ('release', 'publish', 'tag a version').
• Be specific. 'Helps with documents' matches everything and nothing.
• Write it in the third person ('Cuts a new release...'), since it sits in the agent's instructions next to every other skill's description.

When to write a skill

A skill earns its place when you find yourself explaining the same process to an agent more than once, when a task has steps that must happen in a set order, or when getting it wrong is costly: releases, database migrations, security reviews, your house style for docs.

It isn't worth writing one for a task the model already does well unaided, or for a one-off job. And a skill is no substitute for a missing tool: if the agent can't reach your issue tracker, no amount of instructions will fix that. Add the tool first, then teach the workflow.

Common mistakes

• A vague description, so the agent never loads the skill when it should.
• Putting everything in SKILL.md. The whole file loads once the skill triggers, so keep it focused (the specification suggests under 500 lines) and move long reference material into separate files the agent reads only when needed.
• Explaining what the model already knows. Every line competes for context. Spend words on your team's specifics, not on general background.
• Asking the model to redo exact work. If a step must be right to the character, bundle a script.
• Never testing it. Run the skill on real tasks, watch where the agent goes wrong, then tighten the instructions.

Key takeaways

• Tools let an agent act; skills teach it how to do a job.
• A skill is a folder with a SKILL.md: a name and description, then instructions, plus optional scripts, references and templates.
• Agents read only names and descriptions at first, and open a skill in full when a task matches.
• The description decides when a skill loads, so make it specific.
• Steps, rules, examples, templates and guardrails make an agent's work more repeatable.