optimize-skill

Take one existing framework skill — or a maintainer-supplied set of them — and make it leaner without changing what it does. The skill diagnoses a target against the optimization catalogue distilled from the recent security-suite refactors, proposes the applicable passes, and applies them one at a time as behavior-preserving edits the maintainer confirms. The skill validator (and, for tracker-touching skills, the placeholder linter) is the deterministic gate: it is green before the first pass and green again after the last.

This skill operates only on framework-internal files — SKILL.md bodies, their sibling docs, <project-config> manifests, tool adapters in this repo. It reads no external or attacker-controlled content, so the prompt-injection-defence callout does not apply.

It is the refactoring counterpart to write-skill: write-skill authors a net-new skill; optimize-skill restructures one that already exists. The five passes, their smells, exemplar PRs, mechanics, and behavior-preservation guarantees live in patterns.md; this body is the orchestration.

Adopter overrides

Before running the default behaviour documented below, this skill consults .apache-magpie-local/optimize-skill.md (personal, gitignored) and .apache-magpie-overrides/optimize-skill.md (committed, project-wide) in the adopter repo if it exists, and applies any agent-readable overrides it finds. See docs/setup/agentic-overrides.md for the contract — what overrides may contain, hard rules, the reconciliation flow on framework upgrade, upstreaming guidance.

Hard rule: agents NEVER modify the snapshot under <adopter-repo>/.apache-magpie/. Local modifications go in the override file. Framework changes go via PR to apache/magpie.

Snapshot drift

Also at the top of every run, this skill compares the gitignored .apache-magpie.local.lock (per-machine fetch) against the committed .apache-magpie.lock (the project pin). On mismatch the skill surfaces the gap and proposes /magpie-setup upgrade. The proposal is non-blocking — the user may defer if they want to run with the local snapshot for now.

Inputs

• Target — the skill to optimize, as a skill name (security-issue-import), a directory (.claude/skills/security-issue-import/), or a SKILL.md path. Required for a single-skill run.
• Sweep selector (optional) — --all to diagnose every skill under .claude/skills/ and rank optimization candidates without applying anything, or over:<N> to scope the sweep to SKILL.md files longer than <N> lines (default threshold: 500, the PRINCIPLES.md P14 cap).
• Pass filter (optional) — restrict to named passes from patterns.md, e.g. pass:split or pass:config-lift,out-of-context. Default: propose every applicable pass.

When no target and no sweep selector are given, default to a read-only --all diagnosis and let the maintainer pick a target from the ranked list.

Prerequisites

• uv — runs the skill validator (tools/skill-and-tool-validator) and the placeholder linter. Without it the green-before / green-after gate cannot run; stop and ask the user to install uv.
• git — the behavior-preservation checks rely on git diff / git mv; the skill expects a clean (or intentionally dirty, user-acknowledged) working tree so its own edits are isolable.
• doctoc — regenerates a sibling/anchor TOC after a split changes headings. If absent, surface the manual TOC step instead of silently skipping it.

Step 0 — Pre-flight check

1. Target resolves to a real skill directory containing a SKILL.md. A bad name → stop and list the available skills.
2. Baseline is green. Run the validator on the target (or the whole tree for a sweep) and record the result. If it is already red, stop: optimization is a no-behavior-change operation layered on a passing skill, not a way to fix a broken one. Hand the failures back; the maintainer fixes correctness first.
3. Working tree is isolable. Prefer a clean tree, or a dedicated branch, so the optimization diff is reviewable on its own. If the tree carries unrelated changes, surface them and ask before proceeding.
4. Snapshot is current (see Snapshot drift above) — a stale snapshot means the target on disk may not match the framework the maintainer thinks they are editing.

Step 1 — Diagnose

Run every diagnostic in patterns.md against the target and emit a findings table — one row per detected smell, each naming the pass that addresses it, the evidence (path:line, line count, the offending construct), and an effort/blast-radius note. Diagnosis is read-only; it never edits.

The five smells, in the order the passes below apply them:

1. Oversized body — SKILL.md over the 500-line P14 cap, or a single section that dominates the body. → split pass.
2. Concrete-name leakage — adopter-specific values (a concrete <upstream> repo slug, real list addresses, real IDs) baked into the body instead of resolved from <project-config>. → config-lift pass.
3. In-context bulk read — a step that pulls a whole issue body, rollup comment, or large artefact into the agent context only to touch one field of it. → out-of-context pass.
4. Per-item round-trips — N sequential fetches the skill could issue as one upfront batch. → fetch-upfront pass.
5. No deterministic pre-filter — the skill spends an LLM pass on items a cheap deterministic classifier could skip as obvious no-ops. → preflight-classifier pass.

For a sweep, rank targets by (cap overflow × number of distinct smells) and present the list; apply nothing until the maintainer picks one.

Step 2 — Propose

For the chosen target, propose the applicable passes in the order above (lowest blast radius first: a pure file move before any content lift before any tool rewire). For each proposed pass state: the exact files created/moved, the slimming delta (e.g. "SKILL.md 3425 → ~660 lines, four new siblings"), and the behavior-preservation guarantee from patterns.md.

Propose; do not apply. Wait for the maintainer to pick which passes to run, in which order.

Step 3 — Apply one pass at a time

For each confirmed pass, smallest reversible step first:

• Restructure passes (split, config-lift) move or relocate text with no wording change to the instructions themselves. Use git mv where a whole file relocates; otherwise cut-and-paste the exact bytes and replace the body region with a one-line pointer to the new sibling. Never paraphrase a moved instruction — a behavior-preserving move means the moved bytes are identical.
• Rewire passes (out-of-context, fetch-upfront, preflight-classifier) change how a step runs, not what decision it reaches. They route through an existing deterministic tool (e.g. github-body-field, github-rollup) or a pre-flight classifier; the human-visible proposals and gates the skill produces are unchanged. If a rewire would alter what the skill proposes to the user, it is a behavior change — stop and route it through normal review, not this skill.

After each pass: regenerate the doctoc TOC if headings moved, and re-run the validator. One pass per commit keeps the diff reviewable and the git mv rename-detection intact.

Step 4 — Validate (green-after gate)

Re-run the validator (and the placeholder linter for tracker- touching skills) on the optimized target. It must return the same green it returned at Step 0. Then prove behavior preservation:

• For restructure passes, confirm the concatenation of SKILL.md + new siblings contains the same instruction bytes as the original (a moved-not-changed check: git diff should show deletions in SKILL.md matching additions in the siblings, plus the new pointer lines).
• For rewire passes, confirm the skill's proposal/apply surface — the things a human signs off on — is unchanged; only the in-context cost or round-trip count drops.

If the validator goes red or behavior preservation cannot be shown, revert the pass and hand back; do not ship a half-applied optimization.

Step 5 — Hand back

Summarise per pass: files touched, the slimming delta, validator result, and the behavior-preservation evidence. Do not open a PR or commit unless the maintainer asks — surface the diff and let them review. When they do commit, one pass per commit, subject in the refactor(<skill>): … form the security-suite splits used (e.g. "extract N subdocs to slim SKILL.md A → B lines").

If the run was a sweep, restate the ranked remaining candidates so the maintainer can queue the next one.

Hard rules

• Behavior never changes. This skill restructures and rewires; it never alters what a skill decides, proposes, or asks a human to confirm. A change that alters behavior is out of scope — route it through normal skill editing and review.
• Moved bytes are identical bytes. A split or lift that paraphrases the moved instructions is a behavior change in disguise. Move verbatim; only the surrounding pointer is new.
• Propose before applying. Every pass is a proposal the maintainer confirms (framework Principle 6). Never batch-apply a sweep.
• The validator is the gate. Green before, green after, every pass. A pass that needs the validator relaxed is not an optimization.
• The optimized SKILL.md still obeys P14 — under 500 lines, with every sibling linked exactly one level deep and no unreferenced siblings.
• Never touch the snapshot (<adopter-repo>/.apache-magpie/). Framework-skill optimizations land via PR to apache/magpie.

References

• patterns.md — the five optimization passes: smell, exemplar PR, mechanics, behavior-preservation guarantee, validation.
• write-skill — authoring a net-new skill (this skill's counterpart).
• tools/skill-and-tool-validator — the green-before / green-after gate.
• tools/github-body-field and tools/github-rollup — out-of-context read/PATCH tools the rewire passes route through.
• docs/labels-and-capabilities.md — the capability:* taxonomy and the P14 authorship rule this skill enforces.