A Claude Skill is a folder with a SKILL.md file and whatever scripts or reference notes the job needs. The instructions in that folder teach Claude how to do one thing well. The design problem is easy to state and easy to get wrong: Claude reads the skill's short description on every relevant request, but you only want it reading the full detail when the work actually calls for it. Progressive disclosure is the pattern that resolves that tension. Done well, it keeps Claude quick and on-task. Done poorly, it either buries the useful instructions or floods the context window with detail nobody needed.
What progressive disclosure means in a skill
Progressive disclosure is an old interface idea. Show a person the minimum they need to make the next decision, and let them ask for more when they want it. A well-built Claude Skill applies the same logic to the model. The skill's name and description stay in view at all times. The body of SKILL.md loads only when Claude judges the skill relevant. The deeper reference files load only when a specific step reaches for them. Each layer has to earn its place by being read only when it matters, not by default.
The payoff is concrete. A model that carries less irrelevant text reasons more reliably and costs less per request. For an Australian business running Claude across hundreds of tasks a day, the difference between a lean skill and a bloated one shows up on the monthly bill and in the quality of the output.
The three tiers of a well-designed skill
Think of a skill as three layers, each loaded at a different moment.
Tier 1 is the trigger. The name and a one- or two-line description sit in Claude's view for every request. Their only job is to help Claude decide whether to open the skill. Write them for matching, not for marketing. "Reconcile Xero invoices against bank statements" beats "a powerful finance helper" every time.
Tier 2 is the SKILL.md body. These are the working instructions, ideally a few hundred words. Claude loads them once the skill fires. Cover the common path from start to finish and point to deeper material rather than pasting it in.
Tier 3 is the reference layer. Long tables, edge-case handling, sample code and templates live in separate files that Claude reads by name only when a step needs them. This is where the bulk of your material belongs, out of the way until it is useful.
The discipline is in the boundaries. Anything a request nearly always needs goes up a tier. Anything a request rarely needs goes down one. When you are unsure, push it down. A reference file that loads occasionally costs nothing on the requests that skip it.
The anti-patterns we see most
Most skill problems trace back to a handful of habits.
Front-loading everything into SKILL.md. A 4,000-word body means Claude reads all 4,000 words on every task the skill touches, most of which will never use the rare branches you wrote out in full.
Vague descriptions. If the trigger line reads like a slogan, Claude cannot tell when to open the skill, so it either fires on the wrong tasks or misses the right ones.
Orphaned reference files. Detail sitting in a file that SKILL.md never mentions is detail Claude will not find. Every reference file needs an explicit pointer and a one-line note on when to read it.
Duplicated instructions across tiers. When the same rule lives in two places, they drift apart, and Claude follows whichever one it read last.
A worked example
A Sydney logistics operator came to us with a single skill that handled their entire order-exception process in one 3,800-word SKILL.md. It worked, but every exception task, even a simple address correction, pulled the whole document into context. Their average task cost sat around $0.42, and the model occasionally applied a refund rule meant only for damaged freight.
We restructured it along the three tiers. The description became a tight trigger line. The SKILL.md body shrank to about 350 words covering triage and the three most common exceptions. The refund policy, the carrier-specific tables and the damaged-freight workflow each moved into their own reference file, linked from the body with a note on when to open them. Nothing was deleted; it was just relocated.
Average task cost dropped to about $0.13. Across roughly 600 exceptions a day, that is close to $34,000 a year back in their pocket, and the misapplied refund rule stopped appearing because Claude no longer read it unless the task was genuinely about damaged freight. The skill did less reading and made fewer mistakes, which is the whole point.
A short test before you ship a skill
Before a skill goes live, we run it against a few quick questions.
Can Claude tell from the description alone whether to open this skill? If not, tighten the trigger.
Does the SKILL.md body read cleanly in under a minute and cover the common path? If it sprawls, move detail down a tier.
Is every reference file pointed to from the body with a note on when to read it? If a file is orphaned, link it or delete it.
Does any rule appear in more than one place? If so, keep one copy and reference it.
These four checks catch most of the trouble. They also keep a skill maintainable, because the next person editing it can see exactly which layer a change belongs in.
Progressive disclosure is not a trick. It is good information design applied to a model instead of a person, and it rewards the same restraint. If you are building Claude Skills for an Australian team and want a second set of eyes on the structure before you roll them out, book a short brainstorm with us and we will walk through your setup.
