How Claude Code Skills Load: Progressive Disclosure (2026)

A Claude Code skill costs you almost nothing until it's used. Anthropic's documentation puts the idle cost at roughly 100 tokens per skill, which is its name and description. The instructions, reference files and scripts stay on disk until Claude decides the skill is relevant. That's progressive disclosure, and once you understand its three levels, you'll write shorter skills that trigger more reliably.

Most skill problems trace back to putting content at the wrong level: a 900-line SKILL.md that burns context every time it fires, a vague description that never fires at all, or a reference file buried three links deep that Claude only half reads.

The three levels at a glance

The figures come from Anthropic's Agent Skills overview. They're guidance rather than hard limits, but they tell you where the budget is meant to go.

Level 1: the description is the trigger

At the start of a session, Claude Code puts a listing of every available skill into context: each name plus its description. That listing is all Claude knows about your skills until one fires. When you ask for something, Claude matches the request against those descriptions.

Two consequences follow.

First, the description has to say both what the skill does and when to use it. "Helps with PDFs" gives Claude nothing to match against. "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" gives it a request vocabulary. That example is Anthropic's own.

Second, the listing has a budget. Claude Code's docs say the combined description and when_to_use text for each skill is cut off at 1,536 characters, so put the key use case first. The whole listing is also capped, at 1% of the model's context window by default. When you have more skills than fit, Claude Code drops descriptions for the skills you invoke least. The name stays, but the keywords Claude needs to match your request disappear.

That's the quiet reason a skill that used to trigger stops triggering after you install twenty more. If you're chasing that bug, our guide to why a Claude Code skill isn't triggering walks through the other causes.

You can check where you stand. Run /context and look at the Skills row, which reports the listing's size after the budget is applied. /doctor estimates its context cost and names the biggest contributors, and /skill-doctor lists skills you've never invoked so you can switch them off. If you need more room, the skillListingBudgetFraction setting raises the budget (0.02 is 2%), and skillOverrides can set low-priority skills to "name-only" so they list without a description.

Level 2: SKILL.md is a table of contents

When a skill triggers, Claude reads the SKILL.md body into context. From then on, every line of it takes up space for the rest of that task.

Anthropic's best-practice guide and the Claude Code docs give the same number: keep the SKILL.md body under 500 lines. The guide frames the file as an overview that points Claude to detailed material as needed, "like a table of contents in an onboarding guide."

A good SKILL.md body usually holds:

• the steps of the workflow, in order
• the decisions Claude has to make, and how to make them
• links to the reference files, each with a one-line note on when to read it
• the commands to run for anything deterministic

What doesn't belong there: full API references, long lists of examples, database schemas, style guides, and edge cases that come up once a month. Those go down a level.

There's a second reason to keep it tight. When a long conversation gets compacted, Claude Code re-attaches the skills you invoked, but only the first 5,000 tokens of each, from a shared 25,000-token budget that fills starting with the most recently used skill. A bloated SKILL.md can lose its later sections after compaction, and an older skill can drop out entirely. Put the instructions that must survive near the top.

Level 3: files that cost nothing until they're read

Everything else in the skill folder is Level 3. A typical layout:

invoice-processing/
├── SKILL.md
├── reference/
│   ├── tax-rules.md
│   └── vendor-formats.md
├── templates/
│   └── summary.md
└── scripts/
    └── validate_totals.py

Claude reads reference/tax-rules.md only when the task needs tax rules. If the task is about vendor formats, the tax file never enters context. Anthropic's overview makes the point directly: a skill can bundle dozens of reference files, and the ones a task doesn't need cost zero tokens.

Scripts are the most efficient content in the folder. When Claude runs validate_totals.py, the script's code doesn't load into context, only its output does. A 300-line validation script that prints "Totals match" costs you two words. That's also why scripts beat asking Claude to write the same check from scratch every time: it's cheaper and it gives the same answer twice.

Keep references one level deep

This is the rule people break most. Link every reference file directly from SKILL.md. Don't have SKILL.md point to advanced.md which points to details.md.

Anthropic's guide explains why: when Claude hits a file referenced from another referenced file, it may preview it with something like head -100 rather than reading the whole thing. The detail on line 140 never gets seen.

Give long references a contents list

For any reference file over 100 lines, put a short table of contents at the top. If Claude only previews the file, it at least sees what's in it and can go back for the right section.

A before-and-after

Take a common shape: a team writes one SKILL.md for its code review process, 620 lines covering the review steps, the full style guide, security rules for three languages and twenty worked examples.

Every time it triggers, all 620 lines load, including the Go security rules on a Python pull request.

Split it:

• SKILL.md, about 80 lines. The review steps, the order to check things, and a link table: "Python changes: read reference/python.md. Go changes: read reference/go.md. Unsure how strict to be: read reference/examples.md."
• reference/python.md, reference/go.md, reference/typescript.md. One per language, each with a contents list.
• reference/examples.md. The worked examples.
• scripts/check_secrets.py. The secrets scan that used to be forty lines of regex described in prose.

A Python review now loads the 80-line core plus the Python file. The Go rules stay on disk. The secrets check runs as a script and returns a line of output.

When progressive disclosure works differently

Two cases break the pattern, and both are deliberate.

disable-model-invocation: true. A skill with this flag doesn't put its description in context at all, because Claude isn't allowed to trigger it. It loads in full only when you type /skill-name. Use it for skills with side effects, like deploy or send-message workflows. Our SKILL.md frontmatter reference covers this and the other invocation fields.

Subagents with preloaded skills. When a custom subagent lists skills to preload, their full content is injected at startup, not just the description. That's useful for a specialist agent that always needs the same method, and expensive if you preload skills it rarely uses.

A checklist for your next skill

1. The description says what the skill does and when to use it, with the main use case in the first sentence. 2. The SKILL.md body is under 500 lines, ideally well under. 3. Anything Claude needs only sometimes lives in its own file, linked from SKILL.md with a note on when to read it. 4. No reference file links to another reference file. 5. Reference files over 100 lines start with a contents list. 6. Deterministic checks are scripts, not prose instructions. 7. The instructions that matter most are near the top of SKILL.md.

If you're building your first one, start with our 30-minute skill walkthrough, then come back and apply the checklist. And if your sessions are running up large bills, our guide to cutting Claude Code token costs covers the context problems that live outside your skills. For a head start, Anthropic's skill-creator skill scaffolds the folder structure for you.

FAQ

Do installed skills use tokens when I'm not using them? A little. Each skill's name and description sit in context every session, roughly 100 tokens per skill by Anthropic's estimate. The SKILL.md body and bundled files cost nothing until the skill triggers and Claude reads them.

How long should a SKILL.md file be? Keep the body under 500 lines. That's the figure in both Anthropic's best-practice guide and the Claude Code docs. Move detailed reference material into separate files that SKILL.md links to.

Why does Claude only read part of my reference file? It's usually because the file is linked from another reference file rather than from SKILL.md, so Claude previews it instead of reading it fully. Link every reference directly from SKILL.md and add a contents list to long files.

Does Claude load scripts into context? No. When Claude runs a bundled script, only the output enters context. The script's code stays on disk.

Why did my skill stop triggering after I installed more skills? The skill listing has a character budget of 1% of the context window by default. When it overflows, Claude Code drops descriptions for your least-used skills. Check the Skills row in /context, turn off skills you don't use, or raise skillListingBudgetFraction.