skill-progressive-disclosure-design

A decision aid for splitting Claude skill content between SKILL.md and reference files to balance context efficiency against reliable triggering. It is meant to be used whenever creating a new skill, refactoring an existing one, or when a SKILL.md grows past roughly 300-400 lines, and it treats its recommendations as trade-offs to reason from rather than rules to apply blindly, giving explicit pros and cons for each direction.

A first move is to separate two commonly conflated problems. Triggering — whether Claude invokes the skill at all — is driven entirely by the YAML description and is not affected by file splitting, so a skill that fails to trigger needs a description fix, not a split. Progressive disclosure is what loads after activation: the SKILL.md body always loads, references/* load only when SKILL.md tells the model to read a specific file, and scripts/* execute without loading into context at all. The default guidance is not to split; a monolithic SKILL.md is preferred until there is a real reason, such as exceeding roughly 400 lines with natural branches, empirical evidence that context is being wasted, or large content needed only in narrow conditions.

Three split axes are presented as ones that work: a variant branch where user intent selects exactly one path (for example cloud provider, database engine, framework, output format, or language); a workflow-versus-reference-data split where SKILL.md holds the procedure and references hold lookup material like schemas, error-code tables, or option matrices; and a depth tier where SKILL.md covers the common 80% case and a references file covers edge cases behind a sharp load condition. It also catalogs splits that do not work — topic-based splits where invocations do not cluster by topic, splitting merely to hit a line target without a real branching condition, and placing rare-but-critical content in references where the model may skip it. Each pattern is annotated with why it appears attractive and why it fails.