D3 · Claude Code › Cluster 5 · Skills

5.2 · Progressive Disclosure & Invocation

How & when Claude loads a skill

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:

LevelWhatWhen loadedToken cost
1 · Metadataname + description (from frontmatter)Always — at startup, in the system prompt~100 tokens per skill
2 · InstructionsThe SKILL.md bodyOnly when the skill is triggeredUnder ~5k tokens
3+ · ResourcesBundled files & scriptsAs needed, referenced from the bodyEffectively unlimited (0 until read)
🔑 Only Level 1 (name + description) is always in context. The body and every bundled file stay on disk, costing zero tokens, until the moment they're actually needed. That is the whole point: many skills installed, almost no idle context tax.

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:

FrontmatterYou can invokeClaude can invokeDescription in context?
(default)YesYesYes — full skill loads when invoked
disable-model-invocation: trueYesNoNo — loads only when you type /name
user-invocable: falseNoYesYes — hidden from the / menu
Use 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.
⚠️ A well-written 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

flowchart TD S["Startup"] --> L1["🟢 Level 1: every skill's
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
---
🔑 If a skill isn't triggering, first suspect the 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

Trap: "All of a skill's content is always in context." → Only Level 1 (name + description) is always loaded. The body loads on trigger; bundled files load only when referenced.
Trap: "A bundled script's code counts against context when it runs." → No — Claude executes the script via bash and receives only its output. The script's source never enters the window.
Trap: "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.
Trap: "The skill triggers on the folder name." → Auto-invocation matches the 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.