Introduction
Small business owners hear two contradictory claims about AI agent skills. One says you can install dozens of them and your assistant will simply get smarter. The other warns that every new skill slows the assistant down and eats its context window. Both miss the mechanism that decides which claim is true. That mechanism is called progressive disclosure, and it is the reason a large skill library can stay cheap.
An agent skill, introduced by Anthropic on October 16, 2025 and published as an open standard at agentskills.io in December 2025, is a folder built around a file called SKILL.md. It starts with YAML frontmatter holding two required fields, a name and a description, followed by instructions, plus optional scripts, references, and templates. What matters is when each part is loaded, because an assistant does not read the whole folder at once.
What progressive disclosure actually means
Anthropic describes progressive disclosure as loading information only as a task calls for it, like a manual that starts with a table of contents, then the relevant chapter, then a detailed appendix. The assistant keeps just enough information to know a skill exists and when to use it, and pulls deeper detail only when a real task matches. That solves the central problem of working with AI agents: a context window is finite, but the procedures a business might want an assistant to know are not.
Level 1: Metadata, always loaded
At startup, the agent loads only the name and description of every installed skill into its system prompt. The specification puts this at roughly 100 tokens per skill. Fifty installed skills therefore cost about 5,000 tokens before any work begins, roughly one long paragraph per skill set, not fifty full manuals.
This level is why the description field matters so much. The specification caps the name at 64 characters and the description at 1,024 characters, and requires the description to say both what the skill does and when to use it, including keywords that help the agent match it to a task. A description that only says what a skill is, without saying when to use it, is a signpost with no destination. The agent will walk past it.
Level 2: Instructions, loaded on activation
When a request matches a skill description, the agent reads the full SKILL.md body into context. The specification recommends keeping that body under 500 lines and about 5,000 tokens. This is where the actual procedure lives: step-by-step instructions, examples of inputs and outputs, and common edge cases.
Level 2 is where most skill libraries go wrong. Stuff every example and exception into SKILL.md and the body balloons, so every triggering task pays the full cost. Keep the body to the common case and move the rest to Level 3.
Level 3: Resources, loaded only on demand
The third level covers everything else in the skill folder: reference documents, templates, and scripts. The agent loads a reference file only when the instructions point it there during a task, and loads an asset only when the task needs it. Nothing at this level costs context until it is used.
Scripts work differently: the agent can run one without loading its code into context at all, and only its output enters the conversation. Anthropic’s example is a PDF skill whose Python script extracts form fields. The agent runs it, gets the fields, and never pays context for the code. Deterministic work stays in code, judgement stays in instructions.
The three levels at a glance
| Level | What loads | When | Approximate cost |
|---|---|---|---|
| 1. Metadata | Name and description | At startup, for every skill | About 100 tokens per skill |
| 2. Instructions | Full SKILL.md body | When a task matches the description | Under 5,000 tokens recommended |
| 3. Resources | Reference files, assets, script output | Only when the task needs them | Variable, and zero for unrun scripts |
A worked example for a small business
Imagine a bookkeeping skill for supplier invoices. At Level 1, the assistant knows only its name and a description such as: extracts supplier, date, amount, tax, and due date from invoices, and uses it when an invoice file is provided. That costs about 100 tokens and sits quietly alongside every other skill you own.
When you drop in an invoice, Level 2 loads: the body tells the assistant to pull the five fields, check them against your chart of accounts, and flag anything unclear rather than guessing. For a standard invoice, the job ends there. For unusual tax treatment, the body points to one reference file, and only that file loads. Multiply that discipline across dozens of skills and the saving is what lets a library scale.
How small businesses should use this
First, judge a skill by its description before its instructions. If you cannot tell exactly which requests should trigger it, fix the description first. Second, treat a SKILL.md body over 500 lines as a warning sign, not thoroughness. Split it and keep the common path short. Third, put deterministic work into scripts, because script code costs no context: a validation script beats ten paragraphs on how to add numbers.
Finally, progressive disclosure only controls cost. It does not fix a bad procedure, grant live data access, or rescue a vague description. Quality still comes from clear instructions and testing on real tasks, which is why our testing guide is worth following before a skill reaches the whole team.
FAQ
Does installing more skills slow down every task?
Only slightly, and only at Level 1. Each skill adds about 100 tokens of metadata at startup, so 50 skills cost roughly 5,000 tokens of awareness. Full instructions and reference files load only for the skill a task actually uses, so unused skills do not slow that task down.
What happens if a skill description is vague?
The skill may never trigger, because the description is what the agent matches against your request. The specification requires the description to state what the skill does and when to use it. If either half is missing, the skill is effectively invisible no matter how good its instructions are.
Should SKILL.md contain everything the skill knows?
No. Keep the body under 500 lines and about 5,000 tokens, covering the common case well. Move edge cases, long examples, and reference tables into reference files that load only when the body points to them.
Do scripts eat up context like instructions do?
No. The agent runs a script and only its output enters context, not the code. That makes scripts the cheapest way to add deterministic work, such as validation or extraction, to a skill.
Conclusion
Progressive disclosure is a loading discipline with three levels and a token budget at each. Metadata tells the assistant what exists, instructions cover the common job, and resources wait until a specific task needs them. Respect those levels, and a small team can keep dozens of procedures at hand without paying for all of them on every task.
Sources
- Anthropic, Equipping agents for the real world with Agent Skills, https://www.anthropic.com/research/equipping-agents-for-the-real-world-with-agent-skills
- Agent Skills specification, https://agentskills.io/specification



