skill-progressive-disclosure-design

# 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. ## Default: do not split A monolithic SKILL.md beats a split one until proven otherwise. Split only when at least one is true: - SKILL.md exceeds ~400 lines and content has natural branches. - Empirical evidence (eval transcripts) shows the model wasting context on irrelevant sections. - Specific content is large and only needed in narrow conditions. **Pros of staying monolithic:** ...