| 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
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
