The Mistake
Everything in one file
A skill is just a markdown file (SKILL.md) that tells Claude how to do something, like instructions you'd write for a new hire.
Most people, when the task gets complex, cram everything into that one file: where to find the data, how to pull it, how to analyze it, how to build the report, how to send it. All in one wall of text.
That's the mistake. The more you stuff into the file Claude reads up front, the more it has to juggle, and the more it slips. Anthropic says it plainly in their own docs: the context window is a public good. Everything Claude holds at once, your request, the conversation, every line of your skill, shares the same limited space. A 600-line SKILL.md isn't thorough. It's 600 lines crowding out the five that matter for the step Claude is on right now.
The Fix
Progressive disclosure: load detail only when needed
The fix has a name. You keep SKILL.md short, an overview that points to other files, and you put the details for each step in their own reference files. Claude only opens the file it needs, when it needs it.
It helps to see exactly how Claude loads a skill. There are three levels, straight from Anthropic's documentation:
Metadata
Always loaded · ~100 tokensThe name and description at the top of the file. This is how Claude knows the skill exists and when to use it, without reading the whole thing. It's why you can have 50 skills installed and pay almost nothing for it.
Instructions
When triggered · under 5k tokensThe body of SKILL.md. Loads only when your request matches the skill. This is the part you want to keep lean.
Resources
Only when needed · effectively unlimitedYour reference files and scripts. They cost zero tokens until Claude actually opens them. A skill can bundle a dozen reference files and a giant API doc, and none of it touches the context window until a task needs that specific file.
Think of SKILL.md like the table of contents of a manual. It doesn't contain the whole book. It tells Claude which chapter to flip to.
See It
Before & after: a weekly report skill
Say you're building a skill that produces a weekly data report.
❌ The overloaded way: one file, everything in it
weekly-report/
└── SKILL.md ← where to find data, how to pull it, how to
analyze it, the full report template, AND how
to send it, all in one 500-line file Every time this runs, even for a tiny step, Claude loads the entire thing. The send-the-email instructions clutter context while it's still trying to pull the data.
✅ The progressive-disclosure way: an overview that points to a file per step
weekly-report/
├── SKILL.md ← the overview + workflow checklist
├── reference/
│ ├── data-sources.md ← where the data lives + how to pull it
│ ├── analysis.md ← how to analyze it
│ └── report-format.md ← the exact report template
└── scripts/
└── send_report.py ← the script that sends it And SKILL.md itself stays short, it just routes
--- name: weekly-report description: Builds and sends the weekly data report. Use when the user asks for the weekly report or wants metrics pulled, analyzed, and sent. --- # Weekly Report ## Workflow 1. Pull the data: see reference/data-sources.md 2. Analyze it: see reference/analysis.md 3. Build the report: see reference/report-format.md 4. Send it: run scripts/send_report.py
Now when Claude pulls the data, it opens data-sources.md and nothing else. When it's time to analyze, it opens analysis.md. The report template never enters context until step 3. Each step gets Claude's full, uncluttered attention.
Same instructions. Radically more consistent results.
The Details
7 rules nobody tells you
This is where people who already know about progressive disclosure still mess it up. Straight from Anthropic's best-practices guide:
Keep references one level deep
Every reference file should link directly from SKILL.md. Don't point SKILL.md to advanced.md which points to details.md. When Claude hits a file buried two levels down, it tends to skim it instead of reading the whole thing, so it misses information. Flat beats nested. Always.
Keep SKILL.md under 500 lines
Anthropic's own number. If it's creeping past that, that's your signal to split a section out into its own reference file.
Name files for what's in them
data-sources.md, not doc2.md. Claude navigates your skill like a filesystem. Descriptive names are how it knows which file to open.
Put a table of contents atop any long reference file
For files over ~100 lines, add a TOC at the top. Claude sometimes previews long files instead of reading them whole, and a TOC means it still sees everything that's available.
Write the description to say what AND when, in third person
This is the most important line in the whole skill. It's what Claude reads to decide whether to fire the skill at all. ✅ "Builds and sends the weekly data report. Use when…" ❌ "I can help you with reports."
Scripts get run, not read
When a step is fragile or repetitive (sending an email, validating data), put it in a script. Claude executes it and only the output enters context. The code itself never costs you tokens, and it's more reliable than asking Claude to write the code fresh every time.
Don't over-explain
Anthropic's default assumption: Claude is already very smart. Don't write a paragraph explaining what a PDF is. Only include what Claude wouldn't already know: your specifics, your rules, your edge cases.
Do It In 5 Minutes
Two prompts (no manual work)
You don't have to architect this by hand. Claude builds skills natively. Open Claude Code (or Claude with file access) and paste one of these.
Build a new skill the right way
Copy-paste prompt
I want to build a Claude skill for [describe the task]. Set it up using progressive disclosure, following Anthropic's official best practices: - Keep SKILL.md as a short overview with a workflow that points to reference files. Don't cram every detail into it. - Put the details for each step in its own file under reference/. - Keep all references one level deep (linked directly from SKILL.md, never nested). - Put any fragile or repetitive step into a script under scripts/ that you execute rather than read. - Write a description that says what the skill does AND when to use it, in third person. Here's the task, step by step, the way I'd explain it to a new hire: [walk through it]. Build the full folder structure and every file.
Already have a bloated skill? Refactor it
Copy-paste prompt
Here's my current SKILL.md: [paste it]. Refactor it to use progressive disclosure following Anthropic's best practices: keep SKILL.md as a lean overview, split the step-by-step details into separate reference files (one level deep, descriptively named), and move any fragile or repetitive steps into scripts you execute. Show me the new folder structure and every file.
Claude does the restructuring. You review it. Done in a few minutes.
Go Deeper
Read the official source
I'm not making this up. It's Anthropic's own documented best practice. If you want it straight from the source:
Skill authoring best practices →
The single best page on building skills that actually work. Bookmark this one.
How skills work: the 3 levels →
The overview that explains progressive disclosure and the loading model.
The whole trick: don't put everything in one file. Keep SKILL.md a lean table of contents, push the details into reference files, and let Claude open only what each step needs.
Most people won't do this. They'll keep wondering why their big skills get flaky. Now you know the fix. Go refactor your messiest skill this week. You'll feel the difference immediately.
Work with Me
Want me on your problem for an hour?
Book a 1:1 call and we build the fix live — the workflow you want automated, the tool you can’t crack, whatever’s stuck. Direct, hands-on, no pitch waiting at the end.