Claude Skills Explained: The Three Levels of Progressive Disclosure

A Claude Skill is, physically, a folder. Not a hosted service, not a binary, not a block of text you paste at the top of a conversation — a directory containing a SKILL.md file and whatever else the job needs. Almost everything interesting about Skills follows from that one decision, because a folder is something an agent can open selectively. A prompt cannot be opened selectively. It is either in the conversation or it is not.

Anthropic's documentation describes the arrangement as organised like an onboarding guide you would create for a new team member, and the analogy holds further than it first appears. Nobody reads an onboarding guide cover to cover before starting work. They read the page that matches the question in front of them, and they trust that the rest is still there when they need it. A skill is built on the same wager: that most of a procedure can stay on disk most of the time.

Filesystem first, capability second

Claude operates in a virtual machine with filesystem access. That is the precondition for a skill being a directory rather than a configuration entry, because it lets the agent list a folder, read a file, and follow a reference to another file using the same operations a person would use. Inside that, a skill packages instructions, metadata and optional resources such as scripts and templates.

The result is a capability larger than any single file in the folder. The instructions say how to do the task. A bundled script can perform part of it without being described in prose. A reference document can hold material that gets looked up rather than remembered. What makes those three things a system instead of a pile is the order in which they become visible, which is the part Anthropic calls progressive disclosure — loading information in stages as it is needed rather than consuming context upfront.

Level 1: the two fields that are always loaded

Every skill begins with YAML frontmatter carrying a name and a description. Claude loads that metadata at startup and includes it in the system prompt. It is the only part of the skill present before anyone asks for anything, and until a skill is triggered, only its name and description occupy context.

The description is doing three jobs at once, and separating them explains why so many skills are quietly ignored. It is a label, saying what the thing is called. It is an index entry, the text a request is matched against when Claude decides whether the skill is relevant. And it is a statement of scope, which is why Anthropic's guidance is that it must say both what the skill does and when to use it. A description that only manages the first gives the matcher nothing to match.

Take two versions of the same skill. One is described as filling and validating PDF forms, to be used when a request involves completing or checking a PDF form. The other is described as helping with documents. The first names an action and a situation; the second names neither. A skill whose description names neither will sit unread on disk while the agent does the task the long way — not because the skill failed, but because it was never found.

Level 2: the body, read when the description matches

When a request matches the description, the second level opens: the body of SKILL.md. That is the procedure — workflows, best practices, guidance — and it is written for an agent that has already decided this skill is the right tool for the job. It is where a team writes down the steps it would otherwise repeat in every conversation, and it is where the pointers to deeper material live.

The ordering matters here as much as it does at level 1. The body is not loaded at startup, and it is not loaded just in case. It arrives after a decision has been made, which means the decision has to be makeable from level 1 alone. A skill with a vague description has no way to recover at level 2, because level 2 never gets read.

Level 3: files that open because something pointed at them

The third level is the rest of the folder: additional files referenced from SKILL.md. Anthropic's example is a FORMS.md holding advanced guidance on form filling, kept out of the main instructions so those instructions stay short and the detail is available only when a task needs it. Scripts and templates belong at this level too.

The structural effect is that a skill can carry a great deal of material without carrying it all at once. A folder might hold a main instruction file, a detailed reference, a set of templates and a script, and a given task might touch one of them. Whatever nothing points at stays on disk, and disk is not the scarce resource in an agent. Context is.

That is also where the format lifts the ceiling that prompts run into. A prompt has to be short enough to be worth pasting. A skill's bundled material is bounded by what a directory can hold, because the only part that reaches the model is the part the task actually touched.

Why the order is the design, not a detail

Three consequences follow, and together they are the reason this is worth understanding rather than merely knowing.

• Context is a budget, and always-loaded content is a fixed cost. Everything in a system prompt is paid for on every request, including requests that have nothing to do with that skill. Progressive disclosure turns a fixed cost into a conditional one: a description always, instructions when relevant, references when referenced.

• The description is an interface. It is the only part of a skill guaranteed to be seen, so it is where an author has to think about triggering and not only about content.

• A skill has three maintenance speeds. Metadata changes when the skill should fire differently, the body changes when the workflow changes, and references change when the underlying material does. Keeping them apart stops a reference update from turning into a rewrite of the instructions.

The cost is the mirror image of the benefit. Every level boundary is a place where the model has to make a decision correctly. A description that is too narrow means the skill never fires and the folder is dead weight. One that is too broad means it fires on work it was not built for, and its instructions become a tax on unrelated tasks. Progressive disclosure makes the description load-bearing in a way that a long prompt, always present, never is.

What Anthropic already ships, and where your own skills come from

Anthropic ships pre-built Skills for PowerPoint, Excel, Word and PDF — presentations, spreadsheets, documents and formatted PDF output. They are available on claude.ai, the Claude API, Claude Platform on AWS and Microsoft Foundry, with the caveat that on Foundry they require a Hosted on Anthropic deployment.

Those are the fastest way to see the mechanism rather than read about it. The loading order is identical to that of anything you write yourself; the difference between a pre-built skill and a custom one is who authored the folder, not how it reaches the model.

Custom Skills can be created in Claude Code, uploaded through the Claude API, or added in claude.ai settings. Anthropic's stated benefits for them are the ones you would expect from anything reusable: specialising Claude for domain tasks, creating guidance once instead of repeating it, and composing several skills for multistep work. The last of those follows most directly from the architecture, because if each skill is a folder that opens on demand, a stack of skills costs very little until the work actually needs them.

A skill is not a prompt, and not a connector

Three things get conflated in conversation, and the loading order makes the distinctions easy to hold.

A prompt is conversation-level. It is present from the first turn, it colours everything in that conversation, and it disappears with the conversation. A skill is on demand: it exists before the conversation starts, most of it never enters the conversation at all, and the part that arrives does so because a description matched. That is the difference between telling an agent how to behave and giving it something it can pick up.

A connector is about reach. Connectors are app access, which means they determine what an agent can touch; a skill determines how the agent should do something once it can touch it. A team can hold excellent connectors and still produce inconsistent documents, because access is not procedure. It can also hold excellent skills and still not see the data, because procedure is not access.

Anthropic's documentation treats Skills and the Model Context Protocol as different layers, and the three-level mechanism shows why the separation is clean. The loading order is about when information arrives, not where it came from.

Where the donation fits, in one paragraph

On 22 October 2026, Anthropic donated the Agent Skills standard to the Agentic AI Foundation under the Linux Foundation — the name, the logo, the GitHub organisation and the agentskills.io domain — with engineers from Anthropic, Google, OpenAI and other companies maintaining it as individuals. None of that alters the mechanism above. The folder format, the YAML frontmatter, the loading order and the pre-built document skills are exactly as they were the day before. What changed is who owns the name, which matters a great deal to a standard's long-term stability and not at all to how you write a skill this afternoon.

Reading a skill before you install it

If the three levels are the architecture, they also make a short review checklist. Read the description first, because it decides whether anything else ever happens: it should name what the skill does and when it should be used, in words a request would plausibly use. Read SKILL.md second, because it is the procedure the agent will follow, and it should read like instructions to a competent colleague rather than a summary of what you hope will happen. Read what it references third. Then read the scripts.

That last item is not paranoia. The format allows a skill to carry instructions alongside optional resources, and resources can include executable code. A skill you install is therefore not only text that shapes a conversation; it is a folder that a capable agent will open files from and act on. The level-by-level model tells you exactly where to look, which is more than most installed things offer.

One boundary is worth stating for readers who arrive from our own pages. OrcaRouter routes model calls, and we host none of Anthropic's apps or its skill surfaces — a skill runs wherever the agent's filesystem is, and that is not our layer. What we do sits underneath the model choice: more than 200 models behind one OpenAI-compatible key, provider list price passed through with no markup, and automatic failover between providers when one is unavailable. A skill decides how a task should be done. A router decides which model does it, and neither layer should need to know much about the other.

Progressive disclosure is honest about the constraint it solves. Context is finite, procedures are long, and most of any given procedure is irrelevant to the task in front of you. A name, a body and a set of files is not a complicated design; it is the smallest one that lets an agent carry a great deal of knowledge while holding only the part it needs.

Which is why the most consequential line in a well-built skill is also the shortest one. Everything else in the folder is a library. The description is the card catalogue, and when the catalogue is wrong, the library may as well not exist.