# What are agent skills?

Agent skills are folders of instructions, scripts, and files that a coding agent loads when a task calls for them, so it can follow a set procedure.

Last updated September 29, 2026, 8 min read

## Learning objectives

After reading this article you will be able to:

-   Define agent skills
-   Explain when an agent loads a skill
-   Compare skills with MCP servers and instruction files

## Related content

-   [What is a coding agent?](https://specstory.com/learning/ai-coding/coding-agent)
-   [What is AGENTS.md?](https://specstory.com/learning/ai-coding/agents-md)
-   [What is the Model Context Protocol (MCP)?](https://specstory.com/learning/ai-coding/model-context-protocol)
-   [What is an agent harness?](https://specstory.com/learning/ai-coding/agent-harness)
-   [What is context engineering?](https://specstory.com/learning/ai-coding/context-engineering)

## What are agent skills?

Agent skills are packaged folders of instructions, scripts, and reference files that a [coding agent](https://specstory.com/learning/ai-coding/coding-agent) loads when a task matches a skill's description. Each skill has one required file, `SKILL.md`, which holds its name, its description, and the steps to follow. The open format behind them is called Agent Skills.

Anthropic introduced skills for Claude in an [October 2025 announcement](https://claude.com/blog/skills) and later published the format as an open standard. The [Agent Skills site](https://agentskills.io/home) describes it as "a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows." Coding agents from several makers read the format, e.g. GitHub Copilot. Anthropic also publishes example skills on GitHub, in its [`anthropics/skills` repository](https://github.com/anthropics/skills).

A skill gives an agent a procedure it can repeat, e.g. the steps of a release check, without a person pasting those steps into each prompt. Deciding which skills an agent gets is part of [harness engineering](https://specstory.com/learning/ai-coding/harness-engineering), the practice of setting up a coding agent's tools, instructions, checks, and loop.

## How does an agent load a skill?

The [agent harness](https://specstory.com/learning/ai-coding/agent-harness) loads a skill in stages, which the Agent Skills format calls progressive disclosure. One task moves through these steps:

1.  When a session starts, the harness scans its skill folders and reads the name and description in each `SKILL.md`.
2.  The harness adds a list of those names and descriptions to the model's context, without the rest of each file.
3.  A developer gives the agent a task, and the model compares the task with the descriptions in the list.
4.  When a description matches, the model requests the skill with a [tool call](https://specstory.com/learning/glossary#tool-calling), and the harness adds the full `SKILL.md` text to the context.
5.  The model follows the instructions. It reads a bundled file or runs a bundled script only when a step calls for it, and only the script's output enters the context.

Diagram: How an agent loads a skill in stages

Only the list of descriptions is in the context from the start. A skill's instructions and files enter it when a task needs them.

One task can load more than one skill. The format sets no limit on how many skills an agent has, but a product can set one. A person can also start a skill by name, e.g. by typing `/release-check` in Claude Code.

Loading full instructions only when a task needs them is a [context engineering](https://specstory.com/learning/ai-coding/context-engineering) technique.

Claude Code reads project skills from `.claude/skills`. [Codex's documentation](https://learn.chatgpt.com/docs/build-skills) says it scans `.agents/skills` in each folder from the working folder up to the repository root. GitHub Copilot reads project skills from `.github/skills`, `.claude/skills`, or `.agents/skills`. A skill committed to the repository reaches everyone who clones it, but no single folder reaches both Claude Code and Codex.

## What is an example of an agent skill?

Here is an illustrative example. Acme Co. sells furniture online. A developer at Acme adds this file to the web store's repository at `.claude/skills/checkout-check/SKILL.md`:

```text
---
name: checkout-check
description: Check a change to the checkout. Use after edits in checkout/ or cart/.
---
1. Run the unit tests with `npm test`.
2. Create a test cart with 2 items by running `scripts/seed-cart.sh`.
3. Run the checkout test with `npm run test:e2e -- checkout.spec.ts`.
4. Report the result of each command. Do not edit a test to make it pass.
```

The file starts with YAML frontmatter between `---` lines, and the Markdown steps follow it. The folder also holds `scripts/seed-cart.sh`. The format requires the `name` to match the folder name. A session then uses the skill in seven steps:

1.  The harness adds `checkout-check` and its short description to the context.
2.  The developer asks the agent to "Let customers edit their delivery address during checkout."
3.  The agent edits `checkout/AddressForm.tsx`. The edit matches the skill's description, so the model calls the skill.
4.  The harness adds the skill's steps to the context. The agent runs `npm test`, and 42 tests pass.
5.  The agent runs the bundled script, and only its output, `seeded cart: 2 items`, enters the context.
6.  The [end-to-end test](https://specstory.com/learning/testing/end-to-end-testing) fails, because the cart holds 0 items instead of 2. The address saved, but the cart emptied.
7.  The agent changes the address handler to keep the cart, and both tests pass on the rerun.

The unit tests passed on the broken change, because none of them checked the cart. Tasks outside the checkout do not load these steps. This example is simplified. A real skill would also say where the test logs go.

## What are the limits of agent skills?

Skills have these limits:

-   **A skill is a request, not a check.** The model can skip a step and still report "done." A check that must run belongs in an [agent hook](https://specstory.com/learning/ci-cd/agent-hooks), which runs at a fixed point in the loop.
-   **The description controls loading.** A vague description can miss its task, and a broad one can load the skill where it does not fit.
-   **Many skills crowd the list.** When the list outgrows its budget, Claude Code drops the descriptions of the least used skills, so those skills match tasks less often. Codex can leave some skills out with a warning.
-   **A third-party skill runs with the agent's access.** Its text can hide [prompt injection](https://specstory.com/learning/environments/prompt-injection-in-coding-agents), as a [rules file backdoor](https://specstory.com/learning/glossary#rules-file-backdoor) does, and its scripts can send data out.

In Claude Code, a skill's `allowed-tools` field approves tools for the turn that runs it, even in a folder nobody marked as trusted. Reading every file in a skill before installing it can catch a harmful one, and giving the agent [least privilege](https://specstory.com/learning/environments/least-privilege-for-ai-agents) limits what a harmful skill can reach.

## How are skills different from MCP servers?

An MCP server is a separate program that offers tools over the [Model Context Protocol](https://specstory.com/learning/ai-coding/model-context-protocol) (MCP), so the agent can reach a live system. A skill is a folder that the agent reads into its own context and carries out with its existing tools. The two differ on these points:

| Aspect | Agent skill | MCP server |
| --- | --- | --- |
| What it adds | A procedure and reference files | Tools that reach a live system |
| Where its code runs | Through the agent's own shell tool | In the server's own process |
| Context before use | A name and a short description | Tool definitions, unless the harness defers them |

An MCP server fits when the agent needs a system that its built-in tools cannot reach, and a skill fits when it needs a procedure. The two work together. A skill can list which MCP tools to call and in what order, e.g. an order lookup before any checkout edit.

## How are skills different from AGENTS.md?

[AGENTS.md](https://specstory.com/learning/ai-coding/agents-md) is an instruction file that the harness loads when a session starts, so its text is in the context for every task. A skill loads when a task matches its description or a person starts it, and it can bundle scripts and reference files.

[Claude Code's documentation](https://code.claude.com/docs/en/skills) suggests turning a section of an instruction file into a skill when it "has grown into a procedure rather than a fact." A team can keep rules that apply to every task in AGENTS.md, e.g. storing prices as integers in cents, and move procedures with several steps into skills. A rule kept only in a skill is missing from any task that does not load the skill.

## FAQs

### What is SKILL.md?

SKILL.md is the one file that every agent skill folder must contain. Its YAML frontmatter holds the skill's name and description, and its Markdown body holds the steps. The harness reads the frontmatter when a session starts, and the steps load only when the skill is used.

### Where do agent skills live in a repository?

Agent skills in a repository live in a skills folder that the coding agent scans, with one subfolder per skill. Claude Code reads .claude/skills, Codex reads .agents/skills, and GitHub Copilot reads both. Committing the folder shares the skills with everyone who clones the repository and uses an agent that reads it.

### Are third-party skills safe to install?

Third-party skills are only as safe as their source, because a skill's text can carry prompt injection and its scripts run with the agent's access. In Claude Code, a skill can also approve tools for itself. Reading every file before installing a skill, and limiting what the agent can reach, lowers the risk.

### How many skills can an agent load at once?

The number of skills an agent can load has no fixed limit in the Agent Skills format, though a product can set its own cap. One task can use more than one skill. Each skill adds a description to the context, so with many skills some agents drop descriptions, and those skills match tasks less often.

---

Source: [What are agent skills? | Skills vs. MCP | SpecStory](https://specstory.com/learning/ai-coding/agent-skills)