🧮 The context problem
Every conversation with Claude has a finite context window — tokens that disappear when they run out. Loading all 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 costly 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 the minimum required and fetch more as the task’s complexity demands.
name+description in memory- ✓ Dozens of skills installed at no context cost
- ✓ Faster, more focused responses
- ✓ Deep content only when truly needed
- ✓ Context free for the user’s code and conversation
- ✗ Each skill always loads hundreds of tokens
- ✗ 20 skills = 16,000 tokens burned before starting
- ✗ 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 the details of 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 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 using up any meaningful 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 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 long reference content 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 larger than ~1,000 tokens without a good reason
Think of SKILL.md as the briefing you’d give a new team member: complete enough to carry out the task, concise enough to fit into a 5-minute meeting. Deep technical details belong in the references (Layer 3).
3️⃣ Layer 3: references and scripts on demand only
The deepest level: large files such as composition templates, detailed palettes, and shell scripts stay 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 was 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) to assets/fonts/fonts.css.
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 guessing the name.
📈 Why this scales to 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 rendering | With progressive disclosure | Time 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 trigger 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 one that fits best.
Claude doesn’t search literally for keywords. 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 SKILL.md works"
Checks: video-explicativo → "creates HTML→MP4 explainer videos with HyperFrames." ✓ High-confidence match. Check: formato-curso → "creates course HTML pages." ✗ Out of scope here.
Loads the complete SKILL.md for 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 the specific step requires it.
If two skills have overlapping descriptions, Claude may activate the wrong one or get stuck in 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 response is the wrong skill, 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 + descriptionalways stay in memory — ~50 tokens per skill. - ✓Layer 2: the complete SKILL.md is loaded on match — instructions, workflow, and rules of thumb.
- ✓Layer 3: references and scripts (
references/,scripts/) only on demand — when the specific step requires it. - ✓With progressive disclosure, 50 skills use ~94% less context than without it.
- ✓Claude uses semantic matching + TRIGGER/SKIP to decide which skill to activate.