What you will be able to do
- Describe the three levels at which Skill content loads and what each one costs in tokens
- Structure a Skill so that only the content a task needs reaches the context window
- Configure ENABLE_TOOL_SEARCH in the Agent SDK to pick between on-demand and upfront tool loading
1.Three loading levels in Agent Skills
The monolithic alternative to Skills is a long system prompt that holds every workflow, reference and script an agent might need. Agent Skills do the opposite. Each Skill is a directory on the filesystem of Claude's VM, and the Agent Skills overview describes this as an architecture for progressive disclosure: information loads in stages as needed instead of filling context up front.
There are three stages. At startup, Claude loads each Skill's YAML frontmatter, its name and description, into the system prompt. When a request matches a description, Claude reads SKILL.md from the filesystem with bash, and only then does its body enter the context window. Any further files the body references load only if the task needs them. Bundled scripts are run, not read, so only their output reaches context.
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---| Level | When loaded | Token cost | Content |
|---|---|---|---|
| Level 1: Metadata | Always (at startup) | ~100 tokens per Skill | name and description from YAML frontmatter |
| Level 2: Instructions | When Skill is triggered | Under 5k tokens | SKILL.md body with instructions and guidance |
| Level 3+: Resources | As needed | None until accessed | Bundled files; scripts run through bash, and only their output enters context |
The overview's walkthrough shows this in practice. A user asks to extract and summarize a PDF. Claude runs cat pdf-processing/SKILL.md, decides that form filling isn't needed, and never reads FORMS.md. Because unread files cost nothing, a Skill can bundle comprehensive API documentation or large datasets with no context penalty. A monolithic prompt can't do that, since in that design everything you include is paid for on every turn.
Checkpoint 1 of 4· Match them up
Match each piece of Skill content to how it reaches Claude.
Tap a term, then the definition that fits it.
Each kind of content loads at a different stage, and scripts are the only kind whose code never enters context at all.
“When instructions mention executable scripts, Claude runs them through bash and receives only the output (the script code itself never enters context).”Source: platform.claude.com
Checkpoint 2 of 4· Exam question
During testing, an engineering team notices that Claude increasingly selects the wrong tool as more MCP servers are connected to their agent. At what approximate number of simultaneously loaded tools does tool selection accuracy begin to noticeably degrade?
Correct answer: A — Between 30 and 50 tools
- A. Correct. Documentation states tool selection accuracy degrades once more than roughly 30-50 tools are loaded into context at once, which is one of the two core reasons to adopt progressive discovery.
- B. Toolsets this small are well within the range where monolithic loading works fine; accuracy degradation is not documented at this scale.
- C. This range is well past the documented degradation threshold; by this point an agent should already be using tool search rather than just approaching a limit.
- D. This range far exceeds the documented threshold and approaches the catalog-size limits tool search is designed to handle, not the point where accuracy first degrades.
Sources1
2.Writing Skills that keep context lean
Progressive disclosure only works if the Skill is structured for it. The authoring guide starts from the premise that the context window is a public good. A loaded Skill shares it with the system prompt, the conversation history, other Skills' metadata and the user's request. Deferring the body doesn't excuse a bloated body: once Claude loads SKILL.md, every token in it competes with everything else.
The guide's practical rules follow from that. Keep the SKILL.md body under 500 lines, and split content into separate files as it gets close to that limit. Treat SKILL.md as a table of contents that points to FORMS.md, REFERENCE.md or EXAMPLES.md, which load only when needed. For Skills that cover several domains, organize the reference files by domain. Then a sales question reads reference/sales.md and never touches the finance or marketing schemas.
The Level 1 description is the trigger for everything else. Claude matches requests against it, so it has to say both what the Skill does and when to use it. Vague descriptions like "Helps with documents" give Claude nothing to match against.
Checkpoint 3 of 4· Check yourself
A BigQuery Skill puts its finance, sales, product and marketing schemas into one long SKILL.md. What change does the authoring guidance recommend?
Organizing by domain means a question about one area loads only that area's file, which keeps token use low and context focused.
“For Skills with multiple domains, organize content by domain to avoid loading irrelevant context.”Source: platform.claude.com
3.Choosing the strategy in the Agent SDK: ENABLE_TOOL_SEARCH
In the Agent SDK, tools from connected MCP servers face the same choice between on-demand and upfront loading, and the SDK makes it configurable. On Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 and later models, tool search is on by default: definitions are deferred and discovered as needed. You change this with the ENABLE_TOOL_SEARCH environment variable.
The most useful setting for weighing the two strategies is auto. The SDK counts the tokens in the deferrable definitions and compares the total with the model's context window. Once the total reaches 10% of the window, tool search activates. Below that, every definition loads upfront. auto:N uses a custom percentage, and lower values activate tool search sooner. In effect, a small toolset stays monolithic and a large one switches to on-demand discovery.
| Value | Behavior |
|---|---|
| (unset) | Tool search on; falls back to upfront loading on Agent Platform models earlier than the Claude 4.5 generation, a non-first-party ANTHROPIC_BASE_URL, or Microsoft Foundry on Azure |
| true | Always on, except Microsoft Foundry on Azure and Agent Platform models earlier than the Claude 4.5 generation, which still load upfront |
| auto | Activates when deferrable definitions reach 10% of the context window |
| auto:N | Same as auto with a custom percentage, e.g. auto:5 |
| false | Off; all tool definitions loaded into context on every turn |
Checkpoint 4 of 4· Check yourself
An SDK agent sets ENABLE_TOOL_SEARCH to "auto". Its MCP tool definitions add up to 4% of the model's context window. What happens?
auto switches to tool search only when deferrable definitions reach 10% of the window. Below that, the SDK keeps the monolithic upfront loading.
“Below that, the SDK loads every tool definition into context upfront.”Source: code.claude.com
Sources3
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Installed Skills cost zero context until they are triggered.Why is that wrong?
Every installed Skill's name and description load at startup, at about 100 tokens each. What waits for a trigger is the SKILL.md body and the bundled files.
Covered in Three loading levels in Agent Skills
2.Setting ENABLE_TOOL_SEARCH=true forces on-demand tool loading in every deployment.Why is that wrong?
On a Microsoft Foundry deployment hosted on Azure, the server rejects tool search and definitions still load upfront. Pre-4.5 Agent Platform models also keep loading upfront.
Covered in Choosing the strategy in the Agent SDK: ENABLE_TOOL_SEARCH
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“This filesystem-based architecture enables progressive disclosure: Claude loads information in stages as needed, rather than consuming context upfront.”
↩︎ Three loading levels in Agent Skills“Only then does this content enter the context window.”
↩︎ Three loading levels in Agent Skills“Files don't consume context until accessed, so Skills can include comprehensive API documentation, large datasets, or extensive examples.”
↩︎ Three loading levels in Agent Skills“Progressive disclosure ensures only relevant content occupies the context window at any given time.”
↩︎ Three loading levels in Agent Skills“The description is what Claude matches your request against when determining whether to trigger the Skill”
↩︎ Writing Skills that keep context lean“Claude loads this metadata at startup and includes it in the system prompt.”
↩︎ Exam trap 1“until a Skill is triggered, only its name and description occupy context”
↩︎ Prediction“When instructions mention executable scripts, Claude runs them through bash and receives only the output (the script code itself never enters context).”
↩︎ Checkpoint - 2.
“The context window is a public good.”
↩︎ Writing Skills that keep context lean“However, being concise in SKILL.md still matters: once Claude loads it, every token competes with conversation history and other context.”
↩︎ Writing Skills that keep context lean“Keep SKILL.md body under 500 lines for optimal performance”
↩︎ Writing Skills that keep context lean“For Skills with multiple domains, organize content by domain to avoid loading irrelevant context.”
↩︎ Checkpoint - 3.
“Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, and later: tool search is on by default.”
↩︎ Choosing the strategy in the Agent SDK: ENABLE_TOOL_SEARCH“When the total reaches 10% of the window, tool search activates.”
↩︎ Choosing the strategy in the Agent SDK: ENABLE_TOOL_SEARCH“Tool search is off. All tool definitions are loaded into context on every turn.”
↩︎ Choosing the strategy in the Agent SDK: ENABLE_TOOL_SEARCH“Tool search is always on, except on a Microsoft Foundry deployment hosted on Azure, where the server-side rejection still forces upfront loading”
↩︎ Exam trap 2“Below that, the SDK loads every tool definition into context upfront.”
↩︎ Checkpoint