skill-progressive-disclosure-designlisted

# Skill progressive disclosure design ## Contract | Field | Bound contract | |---|---| | Trigger | the model is creating or refactoring a skill, faces a SKILL.md over 300-400 lines, or confuses triggering with disclosure | | Authority | reversible-local: write only named local skill files; rollback by restoring prior file contents | | Side effect | restructures the skill's files (split or monolith with reference pointers), limited to the target skill directory | | Done | justified split-or-monolith decision with pointer hygiene and an architecture-eval plan | ## Inputs - The existing skill directory (`SKILL.md`, any `references/`, `scripts/`). Required. - The skill's YAML description. Required for triggering diagnosis. - Empirical evidence (eval transcripts, token counts) if available. Optional; absence triggers the instrumentation recommendation path. ## Procedure 1. **Diagnose triggering vs. disclosure.** Separate these two problems before deciding whether to split. - **Triggering** is whether the model 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. - **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. This is where context prot