Stop paying 9,758 words to run one git command

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 one for this repo: move detailed guidance out of the always-loaded body into references the model pulls on demand. A SKILL.md body has no partial load — the moment a skill triggers, its entire body is paid. 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. Six of them live in the two plugins this plan touches:

| Skill | Words | Lines |
|---|---|---|
| git-agent/skills/ship-autonomous/SKILL.md | 2,448 | 414 |
| social-media-tools/skills/share-explanation/SKILL.md | 1,863 | 366 |
| git-agent/skills/branch-agent/SKILL.md | 1,515 | 268 |
| social-media-tools/skills/share-session/SKILL.md | 1,414 | 275 |
| social-media-tools/skills/share-selection/SKILL.md | 1,284 | 228 |
| git-agent/skills/ship/SKILL.md | 1,234 | 266 |

Total 9,758 words across two plugins, so two version bumps: git-agent 4.7.0 → 4.8.0 and social-media-tools 2.19.0 → 2.20.0 in .claude-plugin/marketplace.json (refactor = minor).

The git-agent hazard is the whole risk of this plan. ship, ship-autonomous, and branch-agent mutate the working tree, rewrite refs, push to remotes, and end in an irreversible squash merge. ship-autonomous alone carries 22 negative imperatives (never/always/must/do not). A guard that gets relocated into a reference file the model never opens is a guard that no longer exists — and its absence is invisible until the day it should have fired. The rule this plan adopts: guards stay in the SKILL.md core; only procedure detail moves out. A guard is the statement ("never merge on anything but green", "never pass --delete-branch on the strength of a merge approval", "no --no-verify", "cap autofix at 3 attempts per check", "report the git error verbatim, do not retry, do not force", "--no-track or a later push targets the wrong ref"). Procedure detail is the commands and tables that implement it — the gh api graphql review-thread query, the CI failure classification table, the branch-name type-inference table, the stash-pop recovery script. Step 9 of this plan greps for ten specific guard phrases in the six cores, so a guard that slips into a reference file fails the build.

Second hazard, cheaper but easy to get wrong: social-media-tools already has an established layout. Eight of its skills ship a skill-local references/ dir beside SKILL.md (share-blog/references/platforms.md, share-react/references/props-extraction.md, write-guide/references/{exemplars,skeleton,tone-rules}.md, security-scrub/references/scrub-rules.md, share-code, share-video, share-scan, share-project), linked from the body as `Read references/props-extraction.md (bundled with this skill). That is distinct from the plugin-level $PLUGIN_DIR/references/ (platforms, variables, copy-panels, rendering-pipeline, saving-and-delivery, reuse-check, language-map, social-config) which every share-* skill already reads. Match the existing convention exactly: new files go in the skill-local references/, and existing $PLUGIN_DIR/references/... links stay untouched. git-agent has the same shape in create-issue/references/` (5 files, linked from a "Reference files" list at the end of the body).

Third hazard, discovered by reading the tests: tests/plugins/test-ship-self-review.sh greps ship/SKILL.md directly for the Step 4.5 heading (check 2), its position between Step 4 and Step 5 (check 3), by default and --no-review (check 4), the four regression checks accessibility/escaping/truncation/Responsive (check 5), commit --amend --no-edit (check 6), Do not loop a third time (check 7), never blocks the ship (check 8), the Step 7 delegation (check 9), and Edit in allowed-tools (check 10). Moving Step 4.5's detail into a reference file silently breaks six counted assertions — check 5's four terms, check 6, and check 7 — in a test that is not wired into CI. Mitigation: keep the heading and the four policy lines (default-on, --no-review opt-out, non-blocking, reuse Step 7's base) in the core, move only the four-item review checklist and the amend procedure to references/self-review.md, and update the test so those four content checks resolve against the reference file while the policy checks stay on SKILL.md — then prove the updated test still fails by deleting one check from the reference.

Risks and mitigations: (a) behavior drift — a step's meaning changes when its detail moves; mitigated by Step 9's behavioral run of all six skills, not just a word count. (b) dangling links — a reference is named but not written, or written but never linked; mitigated by the objective test resolving every references/*.md mention on disk and failing on orphans in both directions. (c) description drift — a split tempts a rewrite of the frontmatter; the descriptions are budget-checked at 200 chars by tests/plugins/test-description-budget.sh and are the sole trigger surface, so the objective test pins all six to their exact current strings. (d) unbumped versions — mitigated by BASE_REF=main node scripts/check-plugin-versions.mjs.

Out of scope, deliberately: the eleven share-* skills that repeat the same TEMPLATES_DIR locating shell block verbatim. That is a cross-skill dedup with its own blast radius — see Next Steps.