Skill Progressive Disclosure Design

Helps you decide when and how to split a Claude skill between SKILL.md and reference files instead of keeping everything in one file. The default advice is stay monolithic until you have real evidence otherwise, usually around 400 lines or when evals show wasted context. Three patterns that actually work: variant branches (one cloud provider per file), workflow versus lookup data (procedures in SKILL.md, tables in references), and common path versus edge cases. Includes specific anti-patterns like topic splits that sound clean but force multiple loads per invocation. Useful when refactoring an existing skill or when you catch yourself splitting just to hit a line count target.

skills.sh installs: 5.1K
GitHub stars: 242
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add samber/cc-skills --skill skill-progressive-disclosure-design --agent claude-code

Installs into .claude/skills of the current project.

Files

Skill Progressive Disclosure Design

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.

Triggering vs. disclosure: separate these first

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.