Progressive Disclosure in AI Skills: How a Skill Loads Only What It Needs

New to skills? Start with what an AI agent skill is. This post is part two of the series, and it zooms in on the one mechanism that makes skills practical at scale.

What is progressive disclosure?

A skill is a packaged folder of instructions and files an AI model can pick up and use: a set of steps, plus any reference docs or small scripts it might need. Progressive disclosure is the rule for how the model reads that folder. It does not load the whole thing into memory the moment it starts. It reveals the skill in layers and pulls in a layer only when the work calls for it.

Anthropic named this the design principle behind its Agent Skills. The idea is old and boring in the best way. Think of a table of contents. You scan a page of chapter titles first. You open a chapter only when you decide you need it. You do not photocopy the entire book and carry it around just in case.

Two terms do the heavy lifting here, so pin them down. The context window is the model's working memory: the text it can actually see and think about on a single request. A token is the unit that window is measured in, roughly a few characters of text, and every token costs money to process and adds a little time to the answer. A bigger window is not free. Whatever you put in it, you pay for on every request.

How do AI agent skills work? The three levels a skill loads in

Here is the mechanism, in the order it actually runs. Anthropic describes it as three levels: metadata, then instructions, then resources.

Level 1, the metadata, loads at startup. For every skill installed, the model sees only two things: the skill's name and a one or two sentence description of what it does and when to use it. This tiny card is always in memory. Anthropic pegs it at roughly 100 tokens per skill, so the model can carry a long list of these cards at almost no cost.

Level 2, the instructions, load when a task matches. When your request lines up with a skill's description, the model reads the full body of that skill's SKILL.md file: the real procedure, the rules, the steps. Anthropic's own guidance is to keep this body under about 500 lines. It is bigger than the description but still compact, and it enters memory only for the skills that got picked.

Level 3, the resources, load at the last possible moment. Sometimes a single step needs more than the body holds: a long reference table, a detailed spec, a worked example, or a script to run. Those live in the skill's references/ and scripts/ folders, and the model opens them only if a step actually reaches for them. A reference file can run to many thousands of words, because it sits on disk costing nothing until the one moment it is read.

The rule underneath all three: heavy material loads last, and only if used. Most requests never reach level 3 at all.

This works the same way whether the skill runs in the Claude apps, in Claude Code, or behind the Claude API and Agent SDK. Same folder, same layered loading.

To feel why the layering matters, put rough sizes next to each other (illustrative, not a benchmark). A name and description is a couple of sentences. A SKILL.md body is a few hundred to a couple thousand words. A reference doc underneath can be tens of thousands. If every skill dumped its full folder into memory up front, ten skills could bury the model before you asked anything. With progressive disclosure, ten skills or a hundred cost only their little cards until one is needed.

The context window is the model's working memory

The context window AI agents rely on has a hard limit, and everything inside it competes for two things: your money and the model's attention. Every token you load is billed on that request, adds latency, and gives the model one more thing to hold while it reasons. Working memory is finite, and a crowded one makes answers worse, not merely slower.

Progressive disclosure is what keeps a big library of skills cheap. Because only names and descriptions sit resident, you can install dozens or hundreds of skills and the standing cost barely moves. The full instructions arrive only for the skill you triggered. The giant reference doc arrives only for the step that opens it. You get a large catalog of capability with a small, steady memory bill.

This is the part we see directly at Askpert. Sellers package private expertise into protected Experts that run on our servers, built out of skills. A buyer might have many Experts available, but the runtime only ever loads what a given call needs, so a deep catalog stays answerable without a runaway per-call cost. The buyer gets the answer. The private assets stay sealed.

If you have know-how worth packaging, this is the machinery you would be building on. You can author it as a skill in the studio and let the layered loading handle the economics for you.

Progressive disclosure is context engineering

Context engineering is a plain idea with a fancy name: deciding what the model should have in front of it at any given moment. Too little and it guesses. Too much and it slows down, costs more, and loses the thread.

Progressive disclosure is the everyday, built-in form of that discipline. Instead of you hand-picking what goes into each request, the skill format makes "load only what this step needs" the default. The metadata is always there so the model can choose well, and the weight shows up only once a choice has been made.

The description is the hinge

Here's the catch that decides whether any of this works. An agent skill description carries the entire loading decision: the model chooses whether to pull in a skill by reading it, and nothing else. If the description is sharp, the right skill fires at the right time. If it is vague, the skill just sits there. It never loads, and no error tells you why. The capability is installed and silently unused.

Compare two descriptions for the same skill.

Weak: "Helps with marketing."

Sharp: "Audits a Google Ads search campaign and returns specific bid, keyword, and negative-keyword changes. Use when someone shares Google Ads performance data and wants concrete fixes."

The sharp one tells the model exactly when to reach for the skill, so it fires on the right requests and stays out of the way on the rest. The weak one matches everything and nothing. Getting this field right is most of the craft of building a skill, which is why the next post in this series, how to create an AI agent skill, spends real time on it.

On the marketplace we watch this play out in the open. Description quality is often the difference between an Expert that buyers find and call and one that never gets picked up. For domain experts packaging know-how, the description is not the boring part to rush through. It's where the loading decision is actually made, so it's where your care pays off.

The analogy: the specialist and the manual on the shelf

Picture a seasoned specialist at their desk. The thick procedures manual sits on the shelf behind them. They do not read it cover to cover before every task, and they do not carry it around. When one job needs one specific procedure, they turn around, pull the manual down, open it to that page, do the step, and put it back.

The manual is always available. It occupies their attention only for the minute they need it. That is progressive disclosure in one picture: the knowledge is on hand, but it takes up room in the mind only when the task calls for it.

Common questions

Bringing it together

Progressive disclosure earns its keep here: cost and speed track what you actually use, not everything you might install. That's what lets a marketplace list a large catalog of Experts and stay both affordable and fast. If you want to see capabilities built this way, browse the Experts on the marketplace and try one. And when you are ready to build your own, the last post in the series covers every way to create a skill.