Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →samber/skill-progressive-disclosure-design
Decide how to split skill content between SKILL.md and reference files for context efficiency and reliable triggering. Use this whenever creating a new Claude skill, refactoring an existing one, or when a SKILL.md is growing past 300-400 lines. Also trigger when the user mentions "progressive disclosure", "reference files", "splitting skills", "skill bundling", "context window for skills", "SKILL.md too long", "what goes in references/", "skill structure", or expresses any uncertainty about wher
Passed 21 of 22 test cases with the skill, and 11 of 22 without it.
and 15 more in the full report
11 fixed10 passed either way0 still failing1 broke1 errored
Tokens, turns and time describe resource use, not a dollar price.
One of 11 test cases the skill fixed. Same model, same prompt, with and without the skill.
I have a massive SKILL.md for our database migration agent that handles Postgres, MySQL, and SQLite workflows. It is getting bloated and expensive to run, but I am unsure how to reorganize it. Please review this setup and provide an advisory response that diagnoses whether this is a trigger or context issue, quotes relevant parts of our skill description, proposes a minimal file organization, outlines explicit trade-offs with benefits and drawbacks for the recommendation, provides exact routing sentences for any separate files, and suggests how to test the new structure.
| Checked | Without skill | With skill |
|---|---|---|
| proposes separating database engine specifics into variant reference files under references/ rather than topic-based files | Passed | Passed |
| includes explicit pros and cons for the proposed variant branch split | Passed | Passed |
| recommends testing file load rates from execution transcripts to verify reference usage | Missed | Passed |
The instructions your model reads when the skill loads.
Each section that recommends a direction includes explicit pros and cons. The decisions in this skill are trade-offs, not rules. The model using this skill should reason from the trade-offs to the user's specific situation rather than apply rules blindly.
Two problems get conflated and need separating before any splitting decision.
Triggering is whether Claude invokes the skill at all. Driven entirely by the YAML description. File splitting does not affect triggering. If the question is "my skill doesn't trigger reliably", do not split files, fix the description (use run_loop.py from the skill-creator skill).
Progressive disclosure is what loads after the skill activates. SKILL.md body always loads. references/* only loads when SKILL.md tells the model to read a specific file. scripts/* executes without loading into context at all. This is where context protection happens.
If the user is asking about splitting because of triggering issues, surface the confusion first and redirect.
A monolithic SKILL.md beats a split one until proven otherwise.
Split only when at least one is true:
Pros of staying monolithic:
Cons of staying monolithic:
test cases passed, vs 11 / 22 without
Published skills whose descriptions closely match this one, with their headline benchmark lift.
More skills from the same source and nearby in the registry, with their headline benchmark lift.