Agent skills

Overview

An agent skill is a folder that teaches an agent how to do one kind of task well. At its centre is a short instruction file called SKILL.md. Next to it can sit scripts the agent may run, reference documents it may read and assets such as templates. The agent does not read all of this at the start. It sees only each skill's name and a one-line description. When a task matches, it opens the full instructions, and only then reads the extra files it needs.

A professional kitchen keeps a box of recipe cards. Cooks do not memorise every recipe, and they do not read the whole box before each shift. They know which cards exist. When an order for a particular dish comes in, they pull that card and follow it, and the result tastes the same whoever is cooking. Skills are recipe cards for agents.

Skills solve a practical problem. Agents are general, but much useful work follows a team's own procedures: how to build a report in the house style, how to fill in a specific form, how to run a release. Putting all of that into one system prompt wastes context and confuses the model. Skills let you keep a large library of procedures while paying for only the ones in use.

What it is

A skill is a directory with a required SKILL.md file and optional supporting folders.

The open specification sets simple rules. The name is lowercase letters, numbers and hyphens, up to 64 characters, and matches the folder name. The description is up to 1,024 characters. Optional fields include a licence, compatibility notes, metadata and an experimental list of pre-approved tools.

A minimal example:

---
name: quarterly-report
description: Build the quarterly board report in the house format. Use when asked for a board pack, quarterly report or QBR deck.
---
# Quarterly report

1. Read references/brand.md for colours and fonts.
2. Load figures from the CSV the user provides.
3. Run scripts/make_charts.py to create the charts.
4. Follow the slide order in references/outline.md.

Where it came from

Anthropic introduced Agent Skills in October 2025 for Claude's apps, Claude Code and the developer platform. The idea built on patterns that coding agents already used, such as project instruction files and reusable prompts, but added two things: a standard folder layout and loading on demand.

In December 2025 Anthropic published the format as an open specification, with a dedicated site, so that other agent products could read the same skill folders. During 2026 a range of coding agents and assistants from other vendors added support, which means a well-written skill can often be reused across tools. Skills can also be shared inside plugins and through marketplaces in tools that support them.

How it works

Progressive disclosure

The core idea is progressive disclosure, loading information in layers.

1. Metadata. At start-up the agent receives the name and description of every installed skill, typically on the order of a hundred tokens each.
2. Instructions. When a request matches a description, the agent reads the full SKILL.md body. The specification recommends keeping this body fairly short.
3. Resources. The agent opens scripts, references and assets only when the instructions direct it to.

Because each layer is loaded only when needed, an agent can have dozens of skills installed without filling its context.

Choosing a skill

The description is the trigger. The model reads it and decides whether the current request fits. A description that says plainly what the skill does and lists the phrases people use, such as "board pack" or "QBR deck", is loaded reliably. A vague description is not.

Scripts make steps reliable

Language models are good at judgement and weak at exact, repetitive work. Skills move the exact parts, such as building a chart, converting a file format or validating output, into scripts. The agent runs the script instead of improvising code each time, so the result is the same on every run. Scripts need an environment that can execute code, ideally a sandbox.

Skills and tools

Skills do not give an agent new access to outside systems. That is the job of tools and MCP servers. A skill tells the agent how to use the tools it already has to carry out a procedure well.

Key concepts and terms

A worked example

This is an illustrative scenario. A finance team produces a board report every quarter. Each time, people asked an agent for help and got a slightly different layout.

1. The team creates quarterly-report/ with a SKILL.md of about 60 lines: the slide order, rules for rounding figures, a reminder to compare with the previous quarter and a final checklist.
2. references/brand.md holds the colours and fonts. references/outline.md lists 14 slides in order.
3. scripts/make_charts.py reads a CSV of revenue, costs and headcount and saves six charts in the house style.
4. assets/template.pptx is the approved slide template.
5. An executive asks: "Draft this quarter's board pack from the attached figures."
6. The agent sees that the request matches the description, reads SKILL.md, opens the two reference files, runs the chart script and fills the template.
7. It finishes with the checklist from the skill: all 14 slides present, figures rounded to one decimal place, comparison with last quarter on every financial slide.

The team tests the skill on the last three quarters' figures. All three outputs match the approved format, and the skill is added to version control with an owner.

Strengths and limitations

Strengths:

• Consistent results on recurring tasks, whoever asks.
• Low context cost until a skill is actually needed.
• Easy to read, review and version, because skills are plain files.
• Scripts make exact steps deterministic.
• Portable across agent tools that support the open format.

Limitations:

• A vague description means the skill is not loaded when it should be.
• Outdated skills spread outdated practice at scale.
• Scripts from untrusted sources can be harmful.
• Overlapping skills can confuse the agent about which to use.
• Skills cannot add access to new systems on their own.

How it compares with alternatives

Practical guidance and best practices

1. Write a description that says exactly what the skill does and when to use it, including the words people actually say.
2. Keep SKILL.md focused on steps and rules; move long material into reference files.
3. Put deterministic work, such as formatting and validation, into scripts.
4. End the instructions with a short checklist the agent can verify against.
5. Test each skill on real past requests and check that it loads when it should, and not when it should not.
6. Version skills, review changes like code and give each one an owner.
7. Install skills only from trusted sources, and read every script before use; see prompt injection defence.
8. Avoid overlapping skills; merge or sharpen descriptions when two compete.

Common mistakes

• A description such as "helps with documents", which matches everything and nothing.
• Putting a whole manual into SKILL.md instead of using reference files.
• Asking the model to recreate the same chart code every time instead of bundling a script.
• Leaving old skills installed after the process changes.
• Running community scripts without reading them.
• Expecting a skill to give the agent access to a system it cannot already reach.

Frequently asked questions

What is an agent skill?

It is a folder with a SKILL.md instruction file and optional scripts, references and assets. An agent sees the skill's name and description at start-up and loads the rest only when a task needs it.

What is progressive disclosure?

It is loading information in layers. The agent first sees short metadata for every skill, then reads the full instructions of a relevant skill, and finally opens supporting files only when the instructions call for them. This keeps context use low.

Are skills the same as tools?

No. Tools and MCP servers let an agent act on systems, such as reading a database or sending a message. Skills teach the agent how to carry out a type of task, often by using the tools and scripts it already has.

Can skills be used outside Claude?

Yes. The format was published as an open specification in December 2025, and a number of other agent products support it, so the same skill folder can often be used in several tools.

How long should a SKILL.md be?

Short enough to read quickly and follow exactly. Keep the main steps and rules in the file and move long background material, examples and specifications into reference files that load only when needed.

Are skills safe to install?

Treat them like any code you run. Skills can contain scripts and instructions that shape the agent's behaviour, so use trusted sources, read the contents and run scripts in a sandboxed environment.

Glossary

• Skill: a packaged procedure for an agent, stored as a folder.
• SKILL.md: the required instruction file in a skill.
• Front matter: the metadata block with name and description.
• Progressive disclosure: loading context in layers as needed.
• Reference: a supporting document in a skill.
• Script: executable code bundled with a skill.
• Asset: a template or data file used by a skill.
• Trigger: the match between a request and a skill's description.
• Marketplace: a place where skills and plugins are shared.

Summary

Agent skills package procedural know-how as folders that agents load on demand: a SKILL.md with a name, a description and instructions, plus optional scripts, references and assets. Progressive disclosure keeps context use low, scripts make exact steps reliable, and the open format lets skills move between tools. Write precise descriptions, keep instructions focused, test that skills trigger correctly, version them like code and install them only from sources you trust.

Related

It belongs to Coding and computer agents in my stack, under Agentic AI. Others in the same group: