Multi-File Skills and Progressive Disclosure
When One File Isn't Enough
A basic skill is a single SKILL.md, but real skills often need references, examples, or utility scripts. Cramming everything into one 2,000-line file has two problems: it eats context-window space, and it's miserable to maintain. The answer is to apply progressive disclosure to your skill's own files — keep SKILL.md lean and split detail into supporting files Claude reads only when needed.
The 500-line rule of thumb
Keep SKILL.md under 500 lines. If you're exceeding that, the content probably belongs in a separate reference file. Think of SKILL.md as a table of contents that points to deeper material, not the entire library.
The Standard Skill Directory
The open standard suggests a clear directory layout. SKILL.md is the required entrypoint; everything else is optional and loads on demand.
my-skill/
├── SKILL.md # Required — overview + navigation
├── reference.md # Detailed docs, loaded when needed
├── examples.md # Example outputs showing the format
└── scripts/
└── helper.py # Executed, not loaded into contextSKILL.md is always the entrypoint; supporting files load only when the body references them for a given task.
Linking Supporting Files
The trick is to reference supporting files FROM SKILL.md, with clear notes on what each contains and when to load it. That way Claude knows the file exists and pulls it in only for relevant requests — a table of contents in context rather than the whole document.
## Additional resources
- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)
- For architecture questions, read architecture-guide.mdThis is progressive disclosure at the file level
The same principle that keeps skills cheap globally (load name+description, then body) applies inside a skill: load SKILL.md, then its referenced files only as needed. A user asking 'where do I add a component?' never pays for the architecture deep-dive.
Scripts: Run, Don't Read
Scripts in a skill directory can run WITHOUT loading their contents into context. The script executes and only its OUTPUT consumes tokens. The key instruction in your SKILL.md is to tell Claude to RUN the script, not read it — and reference it with ${CLAUDE_SKILL_DIR} so the path resolves wherever the skill is installed.
---
name: codebase-visualizer
description: Generate an interactive tree visualization of your codebase.
Use when exploring a repo or understanding project structure.
allowed-tools: Bash(python3 *)
---
Run the visualization script from your project root:
```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .
```- •Best for: environment validation, consistent data transformations, operations that are more reliable as tested code than generated code.
- •Reliability: a tested script behaves identically every run, unlike regenerated code.
- •Efficiency: deterministic logic stays out of context entirely.
- •Portability: ${CLAUDE_SKILL_DIR} resolves at personal, project, or plugin scope.
Next
Supporting files and scripts make skills powerful. Next: dynamic context injection — running shell commands to inline live data into a skill before Claude even sees it.
Key Takeaways
- ✓Multi-file skills apply progressive disclosure to their own files: keep SKILL.md lean and split detail into supporting files loaded on demand.
- ✓Rule of thumb: keep SKILL.md under 500 lines; beyond that, move content to reference files.
- ✓Standard directory layout: SKILL.md (required entrypoint) + references/ (docs), examples, assets/, scripts/ (executable).
- ✓Reference supporting files from SKILL.md with notes on what they contain and when to load them — Claude pulls them in only for relevant requests.
- ✓Scripts run WITHOUT loading their source — only the output consumes tokens — so tell Claude to RUN the script, not read it.
- ✓Reference bundled scripts with ${CLAUDE_SKILL_DIR} so the path resolves at personal, project, or plugin scope; scripts shine for validation and consistent, tested operations.
Check Your Understanding
Test what you learned in this lesson.
Q1.What is the rule of thumb for SKILL.md length?
Q2.How do supporting files in a skill get loaded?
Q3.Why do bundled scripts keep a skill context-efficient?
Q4.Why reference a bundled script with ${CLAUDE_SKILL_DIR}?
Practice This Lesson