Stop paying 10,776 words for guidance nobody reads yet

Context

The story behind this plan — what prompted the work and why it matters now.

Anthropic's "The new rules of context engineering for Claude 5 generation models" makes progressive disclosure (Rule 3) the load-bearing rule for skill authoring: move detailed guidance out of the always-loaded body into references the model pulls when it needs them, and split long skills into multiple files. A SKILL.md body is paid in full whenever the skill triggers — there is no partial load, no lazy paragraph. A measured audit of this repo found 17 SKILL.md files over 1,200 words shipping as a single file with zero sibling reference files. Five of them live in one plugin, plan-agent: build (2,907 words), finalize-plan (2,764), documenting-plans (1,897), plan-status (1,681), setup-sites (1,527) — 10,776 words in one plugin, and one plugin means one version bump.

build is the clearest case. Its ## Step 1b — Author a plan first (the no-plan chain) runs from line 159 to line 219 — about 60 lines of delegation contract, proposal-versus-direct gating, and return-path rules — and it fires only when the skill is invoked with no plan named. Every ordinary /plan-agent:build docs/plans/x.md pays for all of it and reads none of it. The three mandatory gates (Steps 3, 4, 5, lines 227-303) are the same shape: ~80 lines of verification mechanics that matter at the end of a run, not at the trigger. finalize-plan carries an entire ## Sweep mode (--all) section plus a duplicated legacy-HTML-surgery path; plan-status carries a full ## Bulk mode branch; setup-sites carries four embedded shell blocks.

The pattern is already proven inside this very plugin. kit/plugins/plan-agent/skills/implementation-plan/ ships guidelines/planning-principles.md, guidelines/section-catalog.md, guidelines/right-sizing.md, guidelines/writing-style.md, and reference/SKELETON.md, and its core says explicitly: "read the full file when the step calls for it, not all up front". code-testing-agent and wcag-compliance-reviewer do the same with references/ dirs. This plan copies that pattern, using references/ (the plural, dominant spelling in the repo and the name build-dist.mjs already whitelists).

Risk: silent behavior change. Moving 60 lines of contract into another file can drop a rule. Mitigation: tests/plugins/test-build-skill.sh already pins 18 checks' worth of build's exact contract phrases — the Step 1b delegation calls, the discovery cap, the misparse note, the AskUserQuestion-unavailable fallback. That test becomes the behavior-preservation harness: its section extractors are taught to resolve a heading from whichever file now carries it, and every assertion must still pass unchanged. test-finalize-all-flag.sh and test-setup-sites.sh get the same treatment.

Risk: dangling or orphaned references. A reference file nothing links to is dead weight; a link to a file that does not exist is a hole in the workflow. Progressive disclosure only works if the core names every file it expects the model to fetch. Mitigation: the objective test asserts both directions — every references/*.md on disk is linked from its SKILL.md, and every references/<name>.md mentioned in a SKILL.md resolves to a real file.

Risk: description drift. Splitting must not change any frontmatter description — those strings are what makes a skill trigger, and tests/plugins/test-description-budget.sh already enforces the 200-char budget. Mitigation: an explicit git diff check that the five description: lines are byte-identical to main.

Deliberate exception to the ceiling logic: build's re-render subroutine (a four-line bash block) stays in the core rather than moving to a reference, because every single step calls it. Pulling it out would trade one always-paid block for five on-demand fetches of the same four lines.