🧮 The context problem
Every conversation with Claude has a finite context window — tokens that disappear when they run out. Loading all the skills at once would be disastrous for efficiency and response quality.
An LLM’s context window is like a computer’s RAM: finite, valuable, and expensive to use. If Claude loaded the full contents of every installed skill in every conversation, it would run out of context before you even typed the first word.
The solution is the progressive disclosure: load only what’s needed and fetch more as the task’s complexity requires.
name+description in memory- ✓ Dozens of skills installed at no context cost
- ✓ Faster, more focused responses
- ✓ Deep content only when really needed
- ✓ Context left free for the user’s code and conversation
- ✗ Each skill always loads hundreds of tokens
- ✗ 20 skills = 16,000 tokens burned before you even start
- ✗ Quality degradation in long conversations
- ✗ Conflicts between irrelevant skill instructions
1️⃣ Layer 1: name + description always in memory
The lightest level of progressive disclosure. Only the name e a description of each skill are available all the time — minimal cost, maximum visibility.
Claude needs to know that a skill exists and what it's for — but it doesn't need details on how to run it before deciding whether it's relevant. The name is the identifier; the description is the activation trigger.
It's like a book's index: you read the index to decide which chapter to open — you don't read everything at once.
How Claude read it in narration-template.sh (scene s3): "The description is the most important part of all. It’s what Claude reads to decide when to use that skill. The clearer and more specific it is, the better the trigger."
When you open Claude Code, the system automatically reads all the SKILL.md found in the folders .claude/skills/ (project and global) and indexes only name + description of each one.
With 20 skills, the total cost is ~1,000 tokens — a tiny fraction of the context window. Claude knows these tools exist without having consumed anything significant from the context.
At any point in the conversation, Claude compares the request with the available descriptions. If there’s a match, it moves on to Layer 2.
2️⃣ Layer 2: the full SKILL.md loads on match
When the user's task matches a skill's description, Claude loads the full contents of the SKILL.md — instructions, workflow, rules, and visual identity.
When it detects that the user’s request falls within the scope described by the description, Claude does the equivalent of “opening the book to the right chapter.” The entire SKILL.md is loaded into the context at this point — and only at this point.
- ✓ Include real facts: values such as
LEAD=0.5,TAIL=0.9 - ✓ Organize into clear sections with Markdown headers
- ✓ Separate “golden rules” from optional instructions
- ✓ Include links to the reference files (Layer 3)
- ✗ Don’t put content from long references directly in SKILL.md
- ✗ Don't repeat what's in the description in the body of the file
- ✗ Don't omit the exact values (Claude needs real numbers)
- ✗ Don't make SKILL.md longer than ~1,000 tokens without a good reason
Think of SKILL.md as the briefing you would give a new team member: complete enough to carry out the task, concise enough to fit in a 5-minute meeting. In-depth technical details belong in the references (Layer 3).
3️⃣ Layer 3: references and scripts only on demand
The deepest level: large files such as composition templates, detailed palettes, and shell scripts live in references/ and are read only when the task requires them.
O narration-template.sh has ~100 lines. The composition-template.mjs has ~300 lines. Embedding these files in SKILL.md would consume 5,000+ tokens every time the skill is activated — even for tasks that don't need them.
Loaded when the user asks to generate TTS narration — contains the commands npx hyperframes tts, the voice pf_dora --speed 0.98 and the loop ffprobe to measure durations.
Loaded when the user asks to create or adapt the build-index.mjs — contains the scene structure, constants LEAD=0.5, TAIL=0.9, FADE=0.45 and the final INEMA.CLUB CTA scene.
Loaded when Claude encounters layout errors during npx hyperframes lint or inspect — lists known issues and their fixes.
Loaded specifically in step 3 of the workflow, when it's time to download the files .woff2 (Latin subset) for assets/fonts/fonts.css.
The SKILL.md mentions each Layer 3 file with its exact path (e.g., [narration-template.sh](scripts/narration-template.sh)). This lets Claude locate and load the correct file when needed, without having to guess the name.
📈 Why this scales with dozens of skills
With progressive disclosure, you can install 30, 50, or 100 skills without degrading response quality. Context cost grows linearly and predictably — not exponentially.
| Installed skills | Without progressive | With progressive | Savings |
|---|---|---|---|
| 5 skills | ~4,000 tokens | ~250 tokens | 94% less |
| 20 skills | ~16,000 tokens | ~1,000 tokens | 94% less |
| 50 skills | ~40,000 tokens | ~2,500 tokens | 94% less |
A library of 10,000 books doesn't take up more space in your head than one with 10 — because you don't memorize every book; you just know where to find them. Skills work the same way with progressive disclosure.
Each additional skill adds only ~50 tokens to Layer 1 (name + description). The marginal cost of a new skill is almost zero.
- ✓ Write unique, precise descriptions (without overlap)
- ✓ Use explicit TRIGGER/SKIP in the description
- ✓ Keep SKILL.md ≤ 1,000 tokens; move the rest to Layer 3
- ✓ Group related skills into organized subfolders
- ✗ Vague descriptions that activate the wrong skill (false positive)
- ✗ SKILL.md with 5,000+ tokens (weighs as much as 100 skills)
- ✗ Two skills with overlapping descriptions
- ✗ Use the global folder for project-specific skills
Global skills (~/.claude/skills/) are available in every project—use them for universal tools like video-explicativo. Project skills (.claude/skills/) are available only in that project—use them for workflows specific to the client or codebase.
🤔 How Claude decides which skill to activate
The skill selection mechanism isn’t magic: Claude semantically compares the user’s request with each description available in Layer 1 and chooses the best fit.
Claude doesn't do literal keyword matching. It uses semantic understanding to assess whether the intent of the request matches the scope described in the description. That's why “create an explainer video about Docker” triggers the skill video-explicativo even without using those exact words.
E.g.: "I want to make a short video showing how the SKILL.md works"
Checks: video-explicativo → “creates HTML→MP4 explainer videos with HyperFrames.” ✓ High-confidence match. Check: formato-curso → “creates HTML course pages.” ✗ Out of scope here.
Loads the complete SKILL.md from video-explicativo — instructions, workflow, values such as pf_dora --speed 0.98, palette #0D1321, golden rules.
Follow the skill's workflow: Script → Project → Sources → Narration → Composition → Validate → Render. Only look up Layer 3 when a specific step requires it.
If two skills have overlapping descriptions, Claude may activate the wrong one or run into a conflict. Solution: use the clauses TRIGGER when e SKIP in the description to define the scope precisely.
Before finalizing a skill, ask Claude: "If I asked for X, which skill would you activate?". If the wrong skill is returned, rewrite the description with more specificity — add trigger examples in the TRIGGER field and exclusions in the SKIP field.
✅ Module 1.3 Summary
- ✓The context window is finite—loading everything would be inefficient and counterproductive.
- ✓Layer 1:
name + descriptionare always in memory — a cost of ~50 tokens per skill. - ✓Layer 2: the complete SKILL.md is loaded on match — instructions, workflow, and golden rules.
- ✓Layer 3: references and scripts (
references/,scripts/) only on demand—when that specific step requires it. - ✓With progressive disclosure, 50 skills cost ~94% less context than without it.
- ✓Claude uses semantic matching + TRIGGER/SKIP to decide which skill to activate.