What are Agent Skills?

What are Agent Skills?

Agent Skills are a packaging format for the expertise you want an LLM agent to have. A skill is a folder with three things in it: written instructions describing what the skill is for and how to use it, the scripts or tools the agent can run as part of the skill, and the example inputs and outputs that show what good looks like. Drop it in the right place, and an agent like Claude Code automatically picks it up - no model retraining, no plugin install, no configuration file to update.

The format was published by Anthropic as part of their broader push to make agents practical in real-world workflows. The headline post ("Equipping agents for the real world with Agent Skills") frames the goal directly: the long tail of specialised tasks an agent has to handle in a production environment will never fit inside the model itself - it has to live next to the model, loaded on demand. Skills are the shape that loading takes.

A Skill is the simplest way to teach an agent something new.- agentskills.io

The problem they solve

An LLM is generalist by training. It can write code, summarise documents, draft emails, and reason about a thousand other things - but only at the average level the training data captures. The moment you need it to do your work, in your domain, with your conventions, the generalist runs out of road.

There are several ways to bridge the gap, each with its own cost:

• Fine-tune the model. Expensive, slow, freezes you to one version, and the knowledge gets baked into a model file that nobody on the team can read.
• Stuff the prompt with instructions. Works for small bits of context. Falls over when the relevant knowledge runs to thousands of tokens and would need to be loaded for every interaction.
• Build a bespoke integration. Custom tools, custom code, custom prompts. Solves the problem - and creates a parallel system that has to be maintained and shared somehow.

Agent Skills take a different shape. Each piece of specialised expertise is its own folder, version-controlled with the rest of the project, readable by every team member, loaded by the agent only when relevant. The same long tail an LLM cannot fit inside the model fits comfortably inside the repository, where it belongs.

How a skill is structured

A skill is just a folder. By convention, it contains a small number of named files:

The only required file is SKILL.md. It carries the metadata the agent needs to decide whether the skill is relevant - a short name, a description, the situations in which the skill should be applied. The agent reads SKILL.md the same way a new team member would read a README: skim it, file it away, recall it when the relevant kind of work shows up.

The rest of the folder is optional. Scripts let the skill do something - run a tool, call an API, transform a file. References hold the static knowledge the agent should reach for when the skill is active. Examples ground the agent in what a correct output looks like, which dramatically improves how well it follows the skill's intent.

How the agent discovers and uses them

The flow is intentionally simple at the top, with some carefully engineered behaviour underneath.

The matching step is where the design earns its keep. Because the agent uses each skill's short description as the trigger, the long contents of the skill never need to fit in the prompt by default - they only get loaded when the skill is the right tool for the moment. A repository can carry hundreds of skills without any one prompt being polluted by all of them.

The skill registry

agentskills.io is the community-run registry for skills - a public catalogue where teams publish open-source skills for others to install. The site groups skills by category, exposes search, and offers a one-line install flow into Claude Code and other agent runtimes that support the format.

The role the registry plays is straightforward: skills are a portable artifact, so a skill someone wrote for a common task (PDF redaction, JSON validation, OpenAPI spec linting) does not need to be rewritten by every team that needs it. The registry is the place those reusable skills land. Private skills - the ones encoding your own conventions - stay inside your repository, where they should.

The format itself is open, defined by Anthropic but not tied to Claude. Any agent runtime can support the same folder layout, and the registry is one of several places skills can be hosted.

Writing your first skill

The fastest way to internalise how skills work is to write one. The skeleton is short:

That is enough. The next time Claude Code starts a session in the project, the skill is available. The agent will look at the description and decide on its own whether to apply it. Refine the description, the when_to_use, and the instructions until the agent picks up the skill in the situations you want and ignores it in the situations you do not.

Good first skills are small and concrete: a code style guide, a debugging playbook, a deployment checklist. Once those work, larger skills (the ones that include scripts and reference files) become a natural next step.

When to reach for a skill

A skill is the right answer when the knowledge you need to teach the agent has three properties:

• Specialised. Not something the model already knows well. Domain-specific conventions, internal processes, custom toolchains - the kind of work where the generalist falls short.
• Reusable. Something you will want the agent to do more than once, and probably more than once a week.
• Encodable. Something you can write down. If you cannot describe how to do the work in plain English, a skill cannot teach it to the agent either.

For one-shot tasks, a prompt is enough. For knowledge that has to update in real time, a tool or an MCP server is the right shape. For everything in between - the work patterns you find yourself walking the agent through again and again - a skill is the cleanest fit, and the format that scales as your codebase and your agent's responsibilities grow together.