CONCEPT Three levels, three load times
Progressive disclosure is the mechanism that lets you install many skills without paying for them until they're used. A skill's content is loaded in stages, not all at once:
| Level | What | When loaded | Token cost |
|---|---|---|---|
| 1 · Metadata | name + description (from frontmatter) | Always — at startup, in the system prompt | ~100 tokens per skill |
| 2 · Instructions | The SKILL.md body | Only when the skill is triggered | Under ~5k tokens |
| 3+ · Resources | Bundled files & scripts | As needed, referenced from the body | Effectively unlimited (0 until read) |
The plumbing is filesystem-based. When a skill triggers, Claude reads SKILL.md
from disk via bash — only then does the body enter context. If the body references another file
(reference.md, a schema), Claude reads that too, on demand. If the body names a script, Claude
runs it via bash and receives only its output — the script's code never enters the context window.
CONCEPT Who invokes it: model vs. user
By default a skill is invokable both ways: Claude auto-loads it when your request matches the
description, and you can type /skill-name to force it. Two frontmatter fields narrow
this:
| Frontmatter | You can invoke | Claude can invoke | Description in context? |
|---|---|---|---|
| (default) | Yes | Yes | Yes — full skill loads when invoked |
disable-model-invocation: true | Yes | No | No — loads only when you type /name |
user-invocable: false | No | Yes | Yes — hidden from the / menu |
disable-model-invocation: true for actions with side effects you want to time
yourself — /deploy, /commit, /send-slack-message. You don't want Claude
deciding to deploy because the code "looks ready." Use user-invocable: false for background
knowledge that isn't a meaningful command to type.description is what makes auto-invocation fire correctly. State
both what the skill does and when to use it, and lead with the key use case — the listing
truncates each entry's combined text at 1,536 characters, so front-load the trigger keywords users actually say.DIAGRAM Loading stages over a session
name + description in system prompt
(~100 tokens each)"] L1 --> REQ["User request arrives"] REQ --> MATCH{"Matches a
description?"} MATCH -->|"no"| STAY["⚪ Stays at Level 1 only
body never loaded"] MATCH -->|"yes → model-invoked
or /name typed"| L2["🟠 Level 2: read SKILL.md
body via bash (<5k tokens)"] L2 --> NEED{"Body references
a resource?"} NEED -->|"reference.md"| L3R["📄 Level 3: read file on demand"] NEED -->|"script.py"| L3S["⚙️ Level 3: run via bash
(only output enters context)"] NEED -->|"no"| DONE["Complete task from body alone"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class L1 ok; class L2 gate; class L3R gate; class L3S gate; class STAY bad;
CODE A description tuned for auto-invocation
The first skill triggers automatically because its description names the situations a user would
describe. The second is a manual-only workflow — Claude will not fire it on its own.
# Auto-invokable: Claude matches these keywords to your request. --- 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. --- # Manual-only: side effects, so keep timing in the user's hands. --- name: deploy description: Deploy the application to production disable-model-invocation: true ---
description: does it contain the
words a user would actually say? Verify it's listed by asking "What skills are available?", and if
needed invoke it directly with /skill-name.TRADE-OFFS Progressive disclosure vs. everything-in-context
✅ Progressive disclosure
- Install dozens of skills for ~100 tokens each
- Body + resources cost 0 until triggered
- Scripts run without their code entering context
- No practical limit on bundled reference material
⚠️ Loading full skills upfront
- Every skill's body taxes context every turn
- Large reference docs would blow the window
- Only a handful of skills would fit
- (This is what a preloaded subagent does — deliberately)
EXAM TRAPS
user-invocable: false stops Claude from using the skill." → It only
hides the skill from the / menu; Claude can still auto-invoke it. To stop model invocation
you need disable-model-invocation: true.description, not the name. A vague description is the usual reason a skill won't fire.PRACTICE
Q1 · Which of the three levels is always in context, and roughly what does it cost?
Level 1 — the name and description from the frontmatter, about
100 tokens per skill, always loaded at startup. The body (Level 2) and bundled resources (Level 3) stay on
disk until triggered/referenced.
Q2 · You have a /deploy skill and don't want Claude running it on its own. What do you set?
disable-model-invocation: true. That leaves it user-invocable via /deploy
but removes it from Claude's auto-invocation (and drops its description from context). user-invocable:
false would do the opposite — hide it from you while still letting Claude fire it.
Q3 · Why can you install many skills without a big context penalty?
Progressive disclosure: only each skill's name+description (~100 tokens) sits in context. The multi-thousand-token body and any bundled files load lazily — only when the task matches or the body references them — so idle skills are nearly free.