magpie-optimize-skill · git:20260913.a4dd8ba · 2026-09-13 · sha256 7f78534b0d93063c

magpie-optimize-skill git:20260913.a4dd8baA

Name: magpie-optimize-skill
Author: apache

Immutable. This exact content is served forever at /api/v1/blob/7f78534b0d93063c.

---
# SPDX-License-Identifier: Apache-2.0
# https://www.apache.org/licenses/LICENSE-2.0
name: magpie-optimize-skill
family: utilities
mode: Meta
description: |
Optimize an existing framework skill (or sweep a set of them) by
applying the restructuring patterns proven on the security-skill
suite: split an oversized `SKILL.md` into linked sibling docs,
lift concrete/project-specific values out of the body into
`<project-config>` placeholders, replace in-agent-context body
reads with out-of-context tool calls, batch per-item fetches into
a single upfront pass, and add a deterministic pre-flight no-op
classifier ahead of LLM passes. Every change is a behavior-
preserving proposal the maintainer signs off on; the skill
validator must stay green before and after. The refactoring
sibling of `write-skill` (which authors net-new skills).
when_to_use: |
Invoke when a maintainer says "optimize <skill>", "slim down
<skill>'s SKILL.md", "this SKILL.md is too long", "split <skill>
into subdocs", "lift the hardcoded values out of <skill>", "make
<skill> read less into context", or "sweep the skills for P14
violations". Also a natural follow-up to a principles/validator
audit that flags an over-500-line SKILL.md, concrete-name
leakage, or a heavy in-context read. Skip for net-new skills —
that is `write-skill`. Skip when the request is a behavior
change dressed up as an optimization; route those through normal
skill editing + review.
capability: capability:authoring
license: Apache-2.0
---

# optimize-skill

**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*

- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)

## Pre-flight — is this project set up?

Do this **first, before anything else in this skill**, and do it silently: a
couple of file checks, or one CLI call for a marketplace install.

1. **Is a lock present?** If `.apache-magpie.lock` exists, read its
`method`.
2. **A snapshot method** (`svn-zip` / `git-tag` / `git-branch`) →
compare with `.apache-magpie.local.lock`:
- local lock missing → the snapshot was never fetched on this
machine;
- `ref` / `commit` differ → this machine is on a different framework
version than the project pins.
Anything unresolved → **stop and propose `/magpie-setup`** (or
`/magpie-setup upgrade` for a version mismatch).
3. **`method: marketplace`** → the lock is the project's **floor**: a
minimum version and a minimum plugin set, never a pin. Compare the
machine against it.

**First, check `url`.** If it is anything other than
`apache/magpie`, run **nothing**. Name the marketplace the lock
points at, show the commands it would take, and let the user decide.
A lock is a committed file in whatever repository happened to be
opened, and acting on it automatically would make opening a
repository enough to install someone else's code.

Otherwise read the installed state — `claude plugin list --json`, or
the running agent's equivalent — and compare **as PEP 440, not as
strings**: `0.10.0` is newer than `0.9.0`, and `0.2.0` is newer than
`0.2.0.dev202609110041`.

- every floor plugin installed at or above `min_version` →
**silent**; continue the skill;
- a floor plugin absent → `claude plugin install
<plugin>@apache-magpie`;
- a floor plugin below `min_version` → `claude plugin update
<plugin>@apache-magpie`.

**Never** remove a plugin, downgrade one, pin the marketplace to a
tag, or touch a plugin absent from the floor. Being *ahead* of the
floor is the normal case and is not a finding.

Where there is no such CLI, run nothing and print the commands
instead.

4. **Unless step 3 passed silently, stop.** Whichever branch you took —
plugins installed or updated, commands printed because there is no
CLI, or nothing run at all because `url` named another marketplace —
this session is still below the project's floor. Claude Code loads
plugins at session start, so anything just installed is not live
here, and anything only printed has not run at all. Say what ran, or
what to run, and that the session has to be restarted before
re-running this command.

5. **No lock?** Then this is the marketplace install without adoption,
or nothing at all. That is a supported end state, not a fault — what
matters is whether *this skill's* configuration resolves.

6. **Resolve this skill's `requires_config:` frontmatter.** Each file,
per the lookup chain: `.apache-magpie-local/<file>` (gitignored,
personal) first, then `.apache-magpie-overrides/<file>` (committed).
All present → **silent**, carry on.

Any required file missing → **run `/magpie-setup config` for this
skill now**, say that you are doing it and why, then continue into
the work the user actually asked for.

Running it is safe to do unasked because of what it touches: only
`.apache-magpie-local/` and `.git/info/exclude`, both gitignored,
both invisible to every other person and every other clone, and both
undone by deleting a directory. It stages nothing, commits nothing,
and changes nothing about the repository anyone else sees.

Two things it still may not do: **fabricate a value** — anything it
cannot derive from the repository is a question it asks or a `TODO`
it leaves — and **continue past a value it needs but does not have**.

Unlike a plugin below the floor, this needs no restart: the files
are written and read in the same turn, so the interruption ends and
the command proceeds.

7. **Never run `/magpie-setup adopt` unattended.** Adoption commits a
recommendation for every contributor and is a maintainer's decision
taken with the other maintainers. When configuration was just
written locally, add **one line** saying the project can also adopt
Magpie so contributors get this on clone, and name the command.
Then drop it. Do not ask, do not offer to run it, and do not repeat
it on later invocations.

Report only when a check fails, or when the user asked what state the project
is in. `/magpie-setup verify` is the full diagnostic.

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/SKILL.md): `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`](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`](../../../../docs/setup/agentic-overrides.md) (personal, gitignored) and [`.apache-magpie-overrides/optimize-skill.md`](../../../../docs/setup/agentic-overrides.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`](../../../../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
[`setup upgrade`](../../../magpie-setup/skills/setup/upgrade.md).
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`](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`](../../../../tools/skill-and-tool-validator/README.md))
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`](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`](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`](../../../../tools/github-body-field/README.md),
[`github-rollup`](../../../../tools/github-rollup/README.md)) 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`](patterns.md) — the five optimization passes:
smell, exemplar PR, mechanics, behavior-preservation guarantee,
validation.
- [`write-skill`](../write-skill/SKILL.md) — authoring a net-new
skill (this skill's counterpart).
- [`tools/skill-and-tool-validator`](../../../../tools/skill-and-tool-validator/README.md)
— the green-before / green-after gate.
- [`tools/github-body-field`](../../../../tools/github-body-field/README.md)
and [`tools/github-rollup`](../../../../tools/github-rollup/README.md)
— out-of-context read/PATCH tools the rewire passes route through.
- [`docs/labels-and-capabilities.md`](../../../../docs/labels-and-capabilities.md)
— the `capability:*` taxonomy and the P14 authorship rule this
skill enforces.