refactor(skills): extract conditional content to references#804
Merged
Conversation
The core plan template and Deep extensions template were embedded inline in SKILL.md (~1,300 words of template scaffolding). The template is only consulted in Phase 4 when writing the plan, but loaded on every skill invocation. Move both templates to references/plan-template.md. SKILL.md keeps a 1-paragraph stub describing what's in the reference and pointing to it, plus the same "Omit inapplicable sections" guidance. SKILL.md body: 9,426 -> 8,116 words (-14%).
Phase 4 contained 5 maintenance-action flows (Keep, Update, Consolidate, Replace, Delete) inline in SKILL.md, but only one runs per candidate. All five loaded on every skill invocation. Move the per-action flows to references/per-action-flows.md. SKILL.md keeps a Phase 4 stub describing each action in one line so the reader knows which flow to consult, then points at the reference. Update the YAML-safety contract test to read from the reference (where the Replace Flow now lives), not SKILL.md. The test's intent is unchanged — assert that the Replace Flow content carries the YAML-safety pointer to yaml-schema.md. SKILL.md body: 7,929 -> 7,108 words (-10%).
The skill had no references — both Full Mode (10 steps, ~3,000 words) and Targeted Mode (2 steps, ~250 words) were inline. Mode Detection picks one mode at the start, but both modes' content loaded on every invocation. Move Full Mode to references/full-mode.md and Targeted Mode to references/targeted-mode.md. SKILL.md keeps the cross-cutting content (intro, security note, the agent-time/tech-debt callout, Mode Detection table, scripts list, success criteria) plus a 2-line stub pointing each mode at its reference. SKILL.md body: 3,383 -> 346 words (-90%).
LLMpsycho
pushed a commit
to LLMpsycho/compound-engineering-plugin
that referenced
this pull request
May 8, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
SKILL.md content loads at trigger time and is carried through every subsequent tool call and agent dispatch in that session (per AGENTS.md). Three of the heaviest skills had ~5K words of conditional or single-use content inline that the agent only consults under specific conditions. This PR moves that content to references that load on demand.
What moved
references/plan-template.mdreferences/per-action-flows.mdreferences/{full-mode,targeted-mode}.mdCombined: ~5,170 words removed from always-loaded content across the three skills. The
ce-resolve-pr-feedbackreduction (-90%) is the largest single win — it had no references at all, with both modes living inline despite mode detection routing one or the other.Why this shape
These extractions all share the same underlying pattern: blocks that are conditional (run only in certain modes), late-sequence (run only after upstream phases pick them), or single-use (a template scaffolded once at the end). AGENTS.md guidance is to extract such blocks when they represent ~20%+ of the skill, replace with 1-3 line stubs stating the condition and a backtick path reference, and never inline the extracted content via
@. This PR follows that pattern across the three highest-leverage targets identified in a survey of skill body weights.Three commits, one per skill, so each is independently reviewable and revertable:
bcc9f2ab— ce-plan template extraction (-14% on the body)4059226b— ce-compound-refresh per-action flows (-10%)d3e43652— ce-resolve-pr-feedback per-mode flows (-90%)What was preserved
The contract test for the YAML-safety pointer in
ce-compound-refresh's Replace Flow was updated to read from the new reference where the Replace Flow now lives. The test's intent is unchanged — assert that the Replace Flow content carries the pointer toyaml-schema.md. SKILL.md stubs preserve the routing information needed to find the right reference (each action's one-line meaning in the per-action stub, mode descriptions in the per-mode stub).Test plan
bun test— 1,344 pass, 0 fail.bun run release:validate— clean; skill count unchanged at 39, agent count at 49.