Agent Skill

Why you'd careThe problem it solves

You have a system prompt that started at forty lines and is now nine hundred. Most of it is procedure that matters on maybe one turn in twenty: the PDF-redlining rules, the deploy checklist, the house style guide, the escalation matrix someone added after an incident. You pay for every line of it on every request. Worse, the model reads every line on every turn, so the deploy checklist competes for attention with the redlining rules on a turn that involves neither. Deleting anything feels risky, because each block went in for a reason and nobody remembers which. A skill is the structural answer to that specific problem: move the procedure out of the always-on prompt and into a folder the model opens only when the task looks like the one the folder describes.

ConceptWhat it is

An Agent Skill is a directory. Its entry point is a file named SKILL.md: YAML frontmatter carrying at minimum a name and a description, followed by a Markdown body. Alongside it you may ship anything else the body refers to — reference documents, scripts, templates, schemas. That bundle, plus the loader on whichever surface you are running, is the entire mechanism.

What makes it a skill rather than a document is the load model. The name and description are the only parts resident in context by default. When the model judges that the current task matches that description, it reads the full SKILL.md. If the body says “consult references/policy.md before judging a line item”, that file is read at that moment and not before. Three levels, each opened only on demand.

The boundaries follow from that. A skill grants no capability: it cannot call an API, write a file, or return a value to your code. It is text that changes what the model does with capabilities it already has. The moment the thing you want needs a schema and a return value, you want a tool. The moment it has to be true on every single turn, it belongs in the system prompt. A skill is precisely the middle case — procedural knowledge that is expensive to keep resident and useless to keep out of reach.

How it worksThe mechanics

On a filesystem surface the unit is a folder. The loader walks known skill directories at session start, parses each frontmatter, and holds the names and descriptions. Nothing else is read.

expense-report/
├── SKILL.md
├── references/
│   └── policy-2026.md
└── scripts/
    └── validate_receipts.py

The frontmatter is where the routing decision lives. Both keys below are required by the spec and every upload path (Claude Code treats every key as optional); individual surfaces accept further optional keys, which the frontmatter entry in this catalogue covers.

---
name: expense-report
description: Validates an expense report against the 2026 travel policy.
  Use when the user submits receipts, asks whether an expense is
  reimbursable, or mentions a per-diem.
---

# Expense report

1. Read `references/policy-2026.md` before judging any line item.
2. Run `scripts/validate_receipts.py` on the attached files.
...

On Anthropic's Messages API the mechanism is different in an important way: skills ride the code-execution container, so there is no filesystem of yours involved. You name skills in the container parameter and declare the code-execution tool; no beta header is required. As of 2026-09-12 this is the shape:

client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    container={"skills": [
        {"type": "anthropic", "skill_id": "pptx", "version": "latest"}
    ]},
    tools=[{"type": "code_execution_20260521", "name": "code_execution"}],
    messages=[...],
)

A custom skill cannot be named this way until it exists as a registry object — you upload it through the Skills API first and reference the returned skill_id. On Managed Agents the same references live in a skills array on the Agent object rather than on the request.

At a glanceSee it

How a skill stays out of context until its description matches the task at hand.

Where it runsSurfaces and availability

The pattern to read out of that table: skills are an Anthropic-surface feature that does not travel with the model. The same claude-opus-5 weights called through Bedrock's or Vertex's API will not load a skill, because the loader is not there — though Claude Code and the Agent SDK pointed at those providers still load local skill folders, since that loader runs on your machine. If your deployment target is a cloud reseller's API, treat skills as unavailable and plan to inline the procedure or fetch it through a tool. Microsoft Foundry is the one case where the answer depends on how you deployed rather than which model you picked — the same Foundry resource supports skills on a Hosted on Anthropic deployment and rejects them on a Hosted on Azure one. If you are on first-party surfaces, the portability question that actually bites is between Claude Code folders and API skill objects, not between models; custom Skills do not sync between claude.ai and the API, so each is a separate upload — the one bridge is that skills enabled on a claude.ai account can sync down into Claude Code.

ExampleIn the real world

A four-person legal-ops team reviews vendor MSAs. The playbook is nine hundred lines of clause-by-clause fallback positions, and it was living in the system prompt of their review assistant, where it was read on every turn including the ones where someone just asked what a session ID was.

They move it to a folder. SKILL.md is forty lines: the review sequence, the output format, and an instruction to read references/playbook.md before scoring any clause. The description reads “Redlines a vendor contract against our standard playbook. Use when the user attaches or pastes an agreement and asks for review, redlines, risk flags, or a fallback position.”

A reviewer pastes an MSA and asks “anything scary in here?”. The model matches on the description, reads SKILL.md, sees the instruction, reads the playbook, and returns clause-level flags in the house format. The next message in the same session is “what's our standard payment term?” — a one-line answer with no contract attached. That turn never loads the playbook. What the user notices is that the second answer arrives faster and does not arrive wrapped in a risk table.

Not thisWhat it is often confused with

• Not a toola tool has a JSON Schema, produces a request your code executes, and returns a result. A skill has neither schema nor return value. It can tell the model how to file the expense report; only a tool files it.
• Not an MCP serverMCP is a transport-and-discovery protocol that delivers tools from a separate process. A skill is inert text and files. The two often ship together, and a skill's body frequently explains how to drive tools an MCP server provided.
• Not RAGa skill loads whole named files on a trigger. Retrieval selects a few relevant chunks out of a corpus far too large to load at all. If you find yourself wanting to chunk and embed the contents of a skill, you wanted retrieval.
• Not a system promptthe system prompt is resident on every request and shapes every turn. A skill's body is absent until the model reaches for it. That difference is the entire reason skills exist.
• Not a subagenta skill adds instructions to the conversation you are already in. A subagent starts a separate context window. If your actual complaint is “this context is too crowded”, a skill will not fix it.

LimitsWhen not to reach for it

• The instruction applies to every turn.Tone, refusal policy, output language, identity. Put it in the system prompt; making it conditional just adds a way for it to not load.
• The model needs to do something, not know something.Send an email, query a database, open a PR. Define a tool, or connect an MCP server that already exposes one.
• The body would be a knowledge base.Thousands of documents, only a handful relevant per question. That is retrieval; a skill that tries to load it will blow the context window on the first match.
• You are calling Bedrock or Vertex directly.Their APIs have no skill loader, so the folder will simply be ignored (a Claude Code or Agent SDK harness pointed at them is the exception — its loader runs locally). Inline the procedure or serve it through a tool call.
• The whole thing is one sentence.A skill has real overhead — a description to write, a match to get right, a file to maintain. If the content fits in a line of the system prompt, put it there.

RelatedGo deeper