[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-apache-magpie-optimize-skill":3,"mdc--v4pku2-key":40,"related-org-apache-magpie-optimize-skill":1164,"related-repo-apache-magpie-optimize-skill":1319},{"slug":4,"name":4,"fn":5,"description":6,"org":7,"tags":11,"stars":22,"repoUrl":23,"updatedAt":24,"license":25,"forks":26,"topics":27,"repo":35,"sourceUrl":38,"mdContent":39},"magpie-optimize-skill","optimize and restructure framework skills","Optimize an existing framework skill (or sweep a set of them) by\napplying the restructuring patterns proven on the security-skill\nsuite: split an oversized `SKILL.md` into linked sibling docs,\nlift concrete\u002Fproject-specific values out of the body into\n`\u003Cproject-config>` placeholders, replace in-agent-context body\nreads with out-of-context tool calls, batch per-item fetches into\na single upfront pass, and add a deterministic pre-flight no-op\nclassifier ahead of LLM passes. Every change is a behavior-\npreserving proposal the maintainer signs off on; the skill\nvalidator must stay green before and after. The refactoring\nsibling of `write-skill` (which authors net-new skills).\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},"apache","Apache Software Foundation","https:\u002F\u002Fpexgzepcugksgbtrxkhf.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Forg-logos\u002Fapache.png",[12,16,19],{"name":13,"slug":14,"type":15},"Documentation","documentation","tag",{"name":17,"slug":18,"type":15},"Engineering","engineering",{"name":20,"slug":21,"type":15},"Technical Writing","technical-writing",61,"https:\u002F\u002Fgithub.com\u002Fapache\u002Fmagpie","2026-07-12T08:34:00.777774","Apache-2.0",42,[28,8,29,30,31,32,33,34],"agent-skills","automation","claude-code","cve","security","vulnerability-disclosure","vulnerability-management",{"repoUrl":23,"stars":22,"forks":26,"topics":36,"description":37},[28,8,29,30,31,32,33,34],"Agent-assisted maintainership and development framework for Apache projects — Triage, Mentoring, Drafting (agent-authored fixes with human review), and Pairing (developer-side dev-cycle) skills shipping; Agentic Autonomous (auto-merge) on the roadmap.","https:\u002F\u002Fgithub.com\u002Fapache\u002Fmagpie\u002Ftree\u002FHEAD\u002Fskills\u002Foptimize-skill","---\n# SPDX-License-Identifier: Apache-2.0\n# https:\u002F\u002Fwww.apache.org\u002Flicenses\u002FLICENSE-2.0\nname: magpie-optimize-skill\nfamily: utilities\nmode: Meta\ndescription: |\n  Optimize an existing framework skill (or sweep a set of them) by\n  applying the restructuring patterns proven on the security-skill\n  suite: split an oversized `SKILL.md` into linked sibling docs,\n  lift concrete\u002Fproject-specific values out of the body into\n  `\u003Cproject-config>` placeholders, replace in-agent-context body\n  reads with out-of-context tool calls, batch per-item fetches into\n  a single upfront pass, and add a deterministic pre-flight no-op\n  classifier ahead of LLM passes. Every change is a behavior-\n  preserving proposal the maintainer signs off on; the skill\n  validator must stay green before and after. The refactoring\n  sibling of `write-skill` (which authors net-new skills).\nwhen_to_use: |\n  Invoke when a maintainer says \"optimize \u003Cskill>\", \"slim down\n  \u003Cskill>'s SKILL.md\", \"this SKILL.md is too long\", \"split \u003Cskill>\n  into subdocs\", \"lift the hardcoded values out of \u003Cskill>\", \"make\n  \u003Cskill> read less into context\", or \"sweep the skills for P14\n  violations\". Also a natural follow-up to a principles\u002Fvalidator\n  audit that flags an over-500-line SKILL.md, concrete-name\n  leakage, or a heavy in-context read. Skip for net-new skills —\n  that is `write-skill`. Skip when the request is a behavior\n  change dressed up as an optimization; route those through normal\n  skill editing + review.\ncapability: capability:authoring\nlicense: Apache-2.0\n---\n\n\u003C!-- SPDX-License-Identifier: Apache-2.0\n     https:\u002F\u002Fwww.apache.org\u002Flicenses\u002FLICENSE-2.0 -->\n\n\u003C!-- Placeholder convention (see AGENTS.md#placeholder-convention-used-in-skill-files):\n     \u003Cproject-config> → adopting project's `.apache-magpie\u002F` directory\n     \u003Ctracker>        → value of `tracker_repo:` in \u003Cproject-config>\u002Fproject.md\n     \u003Cupstream>       → value of `upstream_repo:` in \u003Cproject-config>\u002Fproject.md\n     \u003Cframework>      → `.apache-magpie\u002Fapache-magpie` in adopters; `.` in\n                        the framework standalone -->\n\n# optimize-skill\n\nTake one existing framework skill — or a maintainer-supplied set of\nthem — and make it leaner without changing what it does. The skill\ndiagnoses a target against the optimization catalogue distilled from\nthe recent security-suite refactors, proposes the applicable passes,\nand applies them one at a time as **behavior-preserving** edits the\nmaintainer confirms. The skill validator (and, for tracker-touching\nskills, the placeholder linter) is the deterministic gate: it is\ngreen before the first pass and green again after the last.\n\nThis skill operates only on **framework-internal files** — `SKILL.md`\nbodies, their sibling docs, `\u003Cproject-config>` manifests, tool\nadapters in this repo. It reads no external or attacker-controlled\ncontent, so the prompt-injection-defence callout does not apply.\n\nIt is the refactoring counterpart to\n[`write-skill`](..\u002Fwrite-skill\u002FSKILL.md): `write-skill` authors a\nnet-new skill; `optimize-skill` restructures one that already exists.\nThe five passes, their smells, exemplar PRs, mechanics, and\nbehavior-preservation guarantees live in\n[`patterns.md`](patterns.md); this body is the orchestration.\n\n---\n\n## Adopter overrides\n\nBefore running the default behaviour documented\nbelow, this skill consults\n[`.apache-magpie-local\u002Foptimize-skill.md`](..\u002F..\u002Fdocs\u002Fsetup\u002Fagentic-overrides.md) (personal, gitignored) and [`.apache-magpie-overrides\u002Foptimize-skill.md`](..\u002F..\u002Fdocs\u002Fsetup\u002Fagentic-overrides.md) (committed, project-wide)\nin the adopter repo if it exists, and applies any\nagent-readable overrides it finds. See\n[`docs\u002Fsetup\u002Fagentic-overrides.md`](..\u002F..\u002Fdocs\u002Fsetup\u002Fagentic-overrides.md)\nfor the contract — what overrides may contain, hard\nrules, the reconciliation flow on framework upgrade,\nupstreaming guidance.\n\n**Hard rule**: agents NEVER modify the snapshot under\n`\u003Cadopter-repo>\u002F.apache-magpie\u002F`. Local modifications\ngo in the override file. Framework changes go via PR\nto `apache\u002Fmagpie`.\n\n---\n\n## Snapshot drift\n\nAlso at the top of every run, this skill compares the\ngitignored `.apache-magpie.local.lock` (per-machine\nfetch) against the committed `.apache-magpie.lock`\n(the project pin). On mismatch the skill surfaces the\ngap and proposes\n[`\u002Fmagpie-setup upgrade`](..\u002Fsetup\u002Fupgrade.md).\nThe proposal is non-blocking — the user may defer if\nthey want to run with the local snapshot for now.\n\n---\n\n## Inputs\n\n- **Target** — the skill to optimize, as a skill name\n  (`security-issue-import`), a directory\n  (`.claude\u002Fskills\u002Fsecurity-issue-import\u002F`), or a `SKILL.md`\n  path. Required for a single-skill run.\n- **Sweep selector** (optional) — `--all` to diagnose every skill\n  under `.claude\u002Fskills\u002F` and rank optimization candidates without\n  applying anything, or `over:\u003CN>` to scope the sweep to SKILL.md\n  files longer than `\u003CN>` lines (default threshold: **500**, the\n  `PRINCIPLES.md` P14 cap).\n- **Pass filter** (optional) — restrict to named passes from\n  [`patterns.md`](patterns.md), e.g. `pass:split` or\n  `pass:config-lift,out-of-context`. Default: propose every\n  applicable pass.\n\nWhen no target and no sweep selector are given, default to a\nread-only `--all` diagnosis and let the maintainer pick a target\nfrom the ranked list.\n\n---\n\n## Prerequisites\n\n- **`uv`** — runs the skill validator\n  ([`tools\u002Fskill-and-tool-validator`](..\u002F..\u002Ftools\u002Fskill-and-tool-validator\u002FREADME.md))\n  and the placeholder linter. Without it the green-before \u002F\n  green-after gate cannot run; stop and ask the user to install\n  `uv`.\n- **`git`** — the behavior-preservation checks rely on\n  `git diff` \u002F `git mv`; the skill expects a clean (or\n  intentionally dirty, user-acknowledged) working tree so its own\n  edits are isolable.\n- **`doctoc`** — regenerates a sibling\u002Fanchor TOC after a split\n  changes headings. If absent, surface the manual TOC step instead\n  of silently skipping it.\n\n---\n\n## Step 0 — Pre-flight check\n\n1. **Target resolves** to a real skill directory containing a\n   `SKILL.md`. A bad name → stop and list the available skills.\n2. **Baseline is green.** Run the validator on the target (or the\n   whole tree for a sweep) and record the result. If it is already\n   **red**, stop: optimization is a no-behavior-change operation\n   layered on a passing skill, not a way to fix a broken one. Hand\n   the failures back; the maintainer fixes correctness first.\n3. **Working tree is isolable.** Prefer a clean tree, or a\n   dedicated branch, so the optimization diff is reviewable on its\n   own. If the tree carries unrelated changes, surface them and ask\n   before proceeding.\n4. **Snapshot is current** (see *Snapshot drift* above) — a stale\n   snapshot means the target on disk may not match the framework\n   the maintainer thinks they are editing.\n\n---\n\n## Step 1 — Diagnose\n\nRun every diagnostic in [`patterns.md`](patterns.md) against the\ntarget and emit a findings table — one row per detected smell, each\nnaming the pass that addresses it, the evidence (`path:line`, line\ncount, the offending construct), and an effort\u002Fblast-radius note.\nDiagnosis is **read-only**; it never edits.\n\nThe five smells, in the order the passes below apply them:\n\n1. **Oversized body** — `SKILL.md` over the 500-line P14 cap, or a\n   single section that dominates the body. → *split* pass.\n2. **Concrete-name leakage** — adopter-specific values (a concrete\n   `\u003Cupstream>` repo slug, real list addresses, real IDs) baked into\n   the body instead of resolved from `\u003Cproject-config>`. →\n   *config-lift* pass.\n3. **In-context bulk read** — a step that pulls a whole issue body,\n   rollup comment, or large artefact into the agent context only to\n   touch one field of it. → *out-of-context* pass.\n4. **Per-item round-trips** — N sequential fetches the skill could\n   issue as one upfront batch. → *fetch-upfront* pass.\n5. **No deterministic pre-filter** — the skill spends an LLM pass on\n   items a cheap deterministic classifier could skip as obvious\n   no-ops. → *preflight-classifier* pass.\n\nFor a sweep, rank targets by (cap overflow × number of distinct\nsmells) and present the list; apply nothing until the maintainer\npicks one.\n\n---\n\n## Step 2 — Propose\n\nFor the chosen target, propose the applicable passes **in the order\nabove** (lowest blast radius first: a pure file move before any\ncontent lift before any tool rewire). For each proposed pass state:\nthe exact files created\u002Fmoved, the slimming delta (e.g. *\"SKILL.md\n3425 → ~660 lines, four new siblings\"*), and the\nbehavior-preservation guarantee from [`patterns.md`](patterns.md).\n\nPropose; do not apply. Wait for the maintainer to pick which passes\nto run, in which order.\n\n---\n\n## Step 3 — Apply one pass at a time\n\nFor each confirmed pass, smallest reversible step first:\n\n- **Restructure passes (split, config-lift)** move or relocate text\n  with **no wording change to the instructions themselves**. Use\n  `git mv` where a whole file relocates; otherwise cut-and-paste the\n  exact bytes and replace the body region with a one-line pointer to\n  the new sibling. Never paraphrase a moved instruction — a\n  behavior-preserving move means the moved bytes are identical.\n- **Rewire passes (out-of-context, fetch-upfront,\n  preflight-classifier)** change *how* a step runs, not *what\n  decision it reaches*. They route through an existing deterministic\n  tool (e.g. [`github-body-field`](..\u002F..\u002Ftools\u002Fgithub-body-field\u002FREADME.md),\n  [`github-rollup`](..\u002F..\u002Ftools\u002Fgithub-rollup\u002FREADME.md)) or a\n  pre-flight classifier; the human-visible proposals and gates the\n  skill produces are unchanged. If a rewire would alter what the\n  skill proposes to the user, it is a behavior change — stop and\n  route it through normal review, not this skill.\n\nAfter each pass: regenerate the doctoc TOC if headings moved, and\nre-run the validator. One pass per commit keeps the diff reviewable\nand the `git mv` rename-detection intact.\n\n---\n\n## Step 4 — Validate (green-after gate)\n\nRe-run the validator (and the placeholder linter for tracker-\ntouching skills) on the optimized target. It **must** return the\nsame green it returned at Step 0. Then prove behavior preservation:\n\n- For restructure passes, confirm the concatenation of `SKILL.md` +\n  new siblings contains the same instruction bytes as the original\n  (a moved-not-changed check: `git diff` should show deletions in\n  `SKILL.md` matching additions in the siblings, plus the new\n  pointer lines).\n- For rewire passes, confirm the skill's proposal\u002Fapply surface —\n  the things a human signs off on — is unchanged; only the\n  in-context cost or round-trip count drops.\n\nIf the validator goes red or behavior preservation cannot be shown,\n**revert the pass** and hand back; do not ship a half-applied\noptimization.\n\n---\n\n## Step 5 — Hand back\n\nSummarise per pass: files touched, the slimming delta, validator\nresult, and the behavior-preservation evidence. Do **not** open a\nPR or commit unless the maintainer asks — surface the diff and let\nthem review. When they do commit, one pass per commit, subject in\nthe `refactor(\u003Cskill>): …` form the security-suite splits used\n(e.g. *\"extract N subdocs to slim SKILL.md A → B lines\"*).\n\nIf the run was a sweep, restate the ranked remaining candidates so\nthe maintainer can queue the next one.\n\n---\n\n## Hard rules\n\n- **Behavior never changes.** This skill restructures and rewires;\n  it never alters what a skill decides, proposes, or asks a human to\n  confirm. A change that alters behavior is out of scope — route it\n  through normal skill editing and review.\n- **Moved bytes are identical bytes.** A split or lift that\n  paraphrases the moved instructions is a behavior change in\n  disguise. Move verbatim; only the surrounding pointer is new.\n- **Propose before applying.** Every pass is a proposal the\n  maintainer confirms (framework Principle 6). Never batch-apply a\n  sweep.\n- **The validator is the gate.** Green before, green after, every\n  pass. A pass that needs the validator relaxed is not an\n  optimization.\n- **The optimized SKILL.md still obeys P14** — under 500 lines, with\n  every sibling linked exactly one level deep and no unreferenced\n  siblings.\n- **Never touch the snapshot** (`\u003Cadopter-repo>\u002F.apache-magpie\u002F`).\n  Framework-skill optimizations land via PR to `apache\u002Fmagpie`.\n\n---\n\n## References\n\n- [`patterns.md`](patterns.md) — the five optimization passes:\n  smell, exemplar PR, mechanics, behavior-preservation guarantee,\n  validation.\n- [`write-skill`](..\u002Fwrite-skill\u002FSKILL.md) — authoring a net-new\n  skill (this skill's counterpart).\n- [`tools\u002Fskill-and-tool-validator`](..\u002F..\u002Ftools\u002Fskill-and-tool-validator\u002FREADME.md)\n  — the green-before \u002F green-after gate.\n- [`tools\u002Fgithub-body-field`](..\u002F..\u002Ftools\u002Fgithub-body-field\u002FREADME.md)\n  and [`tools\u002Fgithub-rollup`](..\u002F..\u002Ftools\u002Fgithub-rollup\u002FREADME.md)\n  — out-of-context read\u002FPATCH tools the rewire passes route through.\n- [`docs\u002Flabels-and-capabilities.md`](..\u002F..\u002Fdocs\u002Flabels-and-capabilities.md)\n  — the `capability:*` taxonomy and the P14 authorship rule this\n  skill enforces.\n",{"data":41,"body":46},{"name":4,"family":42,"mode":43,"description":6,"when_to_use":44,"capability":45,"license":25},"utilities","Meta","Invoke when a maintainer says \"optimize \u003Cskill>\", \"slim down\n\u003Cskill>'s SKILL.md\", \"this SKILL.md is too long\", \"split \u003Cskill>\ninto subdocs\", \"lift the hardcoded values out of \u003Cskill>\", \"make\n\u003Cskill> read less into context\", or \"sweep the skills for P14\nviolations\". Also a natural follow-up to a principles\u002Fvalidator\naudit that flags an over-500-line SKILL.md, concrete-name\nleakage, or a heavy in-context read. Skip for net-new skills —\nthat is `write-skill`. Skip when the request is a behavior\nchange dressed up as an optimization; route those through normal\nskill editing + review.\n","capability:authoring",{"type":47,"children":48},"root",[49,57,71,100,143,147,154,193,219,222,228,261,264,270,401,413,416,422,501,504,510,575,578,584,614,619,724,729,732,738,766,771,774,780,785,860,872,875,881,893,927,939,942,948,975,980,983,989,1065,1068,1074],{"type":50,"tag":51,"props":52,"children":54},"element","h1",{"id":53},"optimize-skill",[55],{"type":56,"value":53},"text",{"type":50,"tag":58,"props":59,"children":60},"p",{},[61,63,69],{"type":56,"value":62},"Take one existing framework skill — or a maintainer-supplied set of\nthem — and make it leaner without changing what it does. The skill\ndiagnoses a target against the optimization catalogue distilled from\nthe recent security-suite refactors, proposes the applicable passes,\nand applies them one at a time as ",{"type":50,"tag":64,"props":65,"children":66},"strong",{},[67],{"type":56,"value":68},"behavior-preserving",{"type":56,"value":70}," edits the\nmaintainer confirms. The skill validator (and, for tracker-touching\nskills, the placeholder linter) is the deterministic gate: it is\ngreen before the first pass and green again after the last.",{"type":50,"tag":58,"props":72,"children":73},{},[74,76,81,83,90,92,98],{"type":56,"value":75},"This skill operates only on ",{"type":50,"tag":64,"props":77,"children":78},{},[79],{"type":56,"value":80},"framework-internal files",{"type":56,"value":82}," — ",{"type":50,"tag":84,"props":85,"children":87},"code",{"className":86},[],[88],{"type":56,"value":89},"SKILL.md",{"type":56,"value":91},"\nbodies, their sibling docs, ",{"type":50,"tag":84,"props":93,"children":95},{"className":94},[],[96],{"type":56,"value":97},"\u003Cproject-config>",{"type":56,"value":99}," manifests, tool\nadapters in this repo. It reads no external or attacker-controlled\ncontent, so the prompt-injection-defence callout does not apply.",{"type":50,"tag":58,"props":101,"children":102},{},[103,105,116,118,123,125,130,132,141],{"type":56,"value":104},"It is the refactoring counterpart to\n",{"type":50,"tag":106,"props":107,"children":109},"a",{"href":108},"..\u002Fwrite-skill\u002FSKILL.md",[110],{"type":50,"tag":84,"props":111,"children":113},{"className":112},[],[114],{"type":56,"value":115},"write-skill",{"type":56,"value":117},": ",{"type":50,"tag":84,"props":119,"children":121},{"className":120},[],[122],{"type":56,"value":115},{"type":56,"value":124}," authors a\nnet-new skill; ",{"type":50,"tag":84,"props":126,"children":128},{"className":127},[],[129],{"type":56,"value":53},{"type":56,"value":131}," restructures one that already exists.\nThe five passes, their smells, exemplar PRs, mechanics, and\nbehavior-preservation guarantees live in\n",{"type":50,"tag":106,"props":133,"children":135},{"href":134},"patterns.md",[136],{"type":50,"tag":84,"props":137,"children":139},{"className":138},[],[140],{"type":56,"value":134},{"type":56,"value":142},"; this body is the orchestration.",{"type":50,"tag":144,"props":145,"children":146},"hr",{},[],{"type":50,"tag":148,"props":149,"children":151},"h2",{"id":150},"adopter-overrides",[152],{"type":56,"value":153},"Adopter overrides",{"type":50,"tag":58,"props":155,"children":156},{},[157,159,169,171,180,182,191],{"type":56,"value":158},"Before running the default behaviour documented\nbelow, this skill consults\n",{"type":50,"tag":106,"props":160,"children":162},{"href":161},"..\u002F..\u002Fdocs\u002Fsetup\u002Fagentic-overrides.md",[163],{"type":50,"tag":84,"props":164,"children":166},{"className":165},[],[167],{"type":56,"value":168},".apache-magpie-local\u002Foptimize-skill.md",{"type":56,"value":170}," (personal, gitignored) and ",{"type":50,"tag":106,"props":172,"children":173},{"href":161},[174],{"type":50,"tag":84,"props":175,"children":177},{"className":176},[],[178],{"type":56,"value":179},".apache-magpie-overrides\u002Foptimize-skill.md",{"type":56,"value":181}," (committed, project-wide)\nin the adopter repo if it exists, and applies any\nagent-readable overrides it finds. See\n",{"type":50,"tag":106,"props":183,"children":184},{"href":161},[185],{"type":50,"tag":84,"props":186,"children":188},{"className":187},[],[189],{"type":56,"value":190},"docs\u002Fsetup\u002Fagentic-overrides.md",{"type":56,"value":192},"\nfor the contract — what overrides may contain, hard\nrules, the reconciliation flow on framework upgrade,\nupstreaming guidance.",{"type":50,"tag":58,"props":194,"children":195},{},[196,201,203,209,211,217],{"type":50,"tag":64,"props":197,"children":198},{},[199],{"type":56,"value":200},"Hard rule",{"type":56,"value":202},": agents NEVER modify the snapshot under\n",{"type":50,"tag":84,"props":204,"children":206},{"className":205},[],[207],{"type":56,"value":208},"\u003Cadopter-repo>\u002F.apache-magpie\u002F",{"type":56,"value":210},". Local modifications\ngo in the override file. Framework changes go via PR\nto ",{"type":50,"tag":84,"props":212,"children":214},{"className":213},[],[215],{"type":56,"value":216},"apache\u002Fmagpie",{"type":56,"value":218},".",{"type":50,"tag":144,"props":220,"children":221},{},[],{"type":50,"tag":148,"props":223,"children":225},{"id":224},"snapshot-drift",[226],{"type":56,"value":227},"Snapshot drift",{"type":50,"tag":58,"props":229,"children":230},{},[231,233,239,241,247,249,259],{"type":56,"value":232},"Also at the top of every run, this skill compares the\ngitignored ",{"type":50,"tag":84,"props":234,"children":236},{"className":235},[],[237],{"type":56,"value":238},".apache-magpie.local.lock",{"type":56,"value":240}," (per-machine\nfetch) against the committed ",{"type":50,"tag":84,"props":242,"children":244},{"className":243},[],[245],{"type":56,"value":246},".apache-magpie.lock",{"type":56,"value":248},"\n(the project pin). On mismatch the skill surfaces the\ngap and proposes\n",{"type":50,"tag":106,"props":250,"children":252},{"href":251},"..\u002Fsetup\u002Fupgrade.md",[253],{"type":50,"tag":84,"props":254,"children":256},{"className":255},[],[257],{"type":56,"value":258},"\u002Fmagpie-setup upgrade",{"type":56,"value":260},".\nThe proposal is non-blocking — the user may defer if\nthey want to run with the local snapshot for now.",{"type":50,"tag":144,"props":262,"children":263},{},[],{"type":50,"tag":148,"props":265,"children":267},{"id":266},"inputs",[268],{"type":56,"value":269},"Inputs",{"type":50,"tag":271,"props":272,"children":273},"ul",{},[274,308,365],{"type":50,"tag":275,"props":276,"children":277},"li",{},[278,283,285,291,293,299,301,306],{"type":50,"tag":64,"props":279,"children":280},{},[281],{"type":56,"value":282},"Target",{"type":56,"value":284}," — the skill to optimize, as a skill name\n(",{"type":50,"tag":84,"props":286,"children":288},{"className":287},[],[289],{"type":56,"value":290},"security-issue-import",{"type":56,"value":292},"), a directory\n(",{"type":50,"tag":84,"props":294,"children":296},{"className":295},[],[297],{"type":56,"value":298},".claude\u002Fskills\u002Fsecurity-issue-import\u002F",{"type":56,"value":300},"), or a ",{"type":50,"tag":84,"props":302,"children":304},{"className":303},[],[305],{"type":56,"value":89},{"type":56,"value":307},"\npath. Required for a single-skill run.",{"type":50,"tag":275,"props":309,"children":310},{},[311,316,318,324,326,332,334,340,342,348,350,355,357,363],{"type":50,"tag":64,"props":312,"children":313},{},[314],{"type":56,"value":315},"Sweep selector",{"type":56,"value":317}," (optional) — ",{"type":50,"tag":84,"props":319,"children":321},{"className":320},[],[322],{"type":56,"value":323},"--all",{"type":56,"value":325}," to diagnose every skill\nunder ",{"type":50,"tag":84,"props":327,"children":329},{"className":328},[],[330],{"type":56,"value":331},".claude\u002Fskills\u002F",{"type":56,"value":333}," and rank optimization candidates without\napplying anything, or ",{"type":50,"tag":84,"props":335,"children":337},{"className":336},[],[338],{"type":56,"value":339},"over:\u003CN>",{"type":56,"value":341}," to scope the sweep to SKILL.md\nfiles longer than ",{"type":50,"tag":84,"props":343,"children":345},{"className":344},[],[346],{"type":56,"value":347},"\u003CN>",{"type":56,"value":349}," lines (default threshold: ",{"type":50,"tag":64,"props":351,"children":352},{},[353],{"type":56,"value":354},"500",{"type":56,"value":356},", the\n",{"type":50,"tag":84,"props":358,"children":360},{"className":359},[],[361],{"type":56,"value":362},"PRINCIPLES.md",{"type":56,"value":364}," P14 cap).",{"type":50,"tag":275,"props":366,"children":367},{},[368,373,375,383,385,391,393,399],{"type":50,"tag":64,"props":369,"children":370},{},[371],{"type":56,"value":372},"Pass filter",{"type":56,"value":374}," (optional) — restrict to named passes from\n",{"type":50,"tag":106,"props":376,"children":377},{"href":134},[378],{"type":50,"tag":84,"props":379,"children":381},{"className":380},[],[382],{"type":56,"value":134},{"type":56,"value":384},", e.g. ",{"type":50,"tag":84,"props":386,"children":388},{"className":387},[],[389],{"type":56,"value":390},"pass:split",{"type":56,"value":392}," or\n",{"type":50,"tag":84,"props":394,"children":396},{"className":395},[],[397],{"type":56,"value":398},"pass:config-lift,out-of-context",{"type":56,"value":400},". Default: propose every\napplicable pass.",{"type":50,"tag":58,"props":402,"children":403},{},[404,406,411],{"type":56,"value":405},"When no target and no sweep selector are given, default to a\nread-only ",{"type":50,"tag":84,"props":407,"children":409},{"className":408},[],[410],{"type":56,"value":323},{"type":56,"value":412}," diagnosis and let the maintainer pick a target\nfrom the ranked list.",{"type":50,"tag":144,"props":414,"children":415},{},[],{"type":50,"tag":148,"props":417,"children":419},{"id":418},"prerequisites",[420],{"type":56,"value":421},"Prerequisites",{"type":50,"tag":271,"props":423,"children":424},{},[425,457,487],{"type":50,"tag":275,"props":426,"children":427},{},[428,437,439,449,451,456],{"type":50,"tag":64,"props":429,"children":430},{},[431],{"type":50,"tag":84,"props":432,"children":434},{"className":433},[],[435],{"type":56,"value":436},"uv",{"type":56,"value":438}," — runs the skill validator\n(",{"type":50,"tag":106,"props":440,"children":442},{"href":441},"..\u002F..\u002Ftools\u002Fskill-and-tool-validator\u002FREADME.md",[443],{"type":50,"tag":84,"props":444,"children":446},{"className":445},[],[447],{"type":56,"value":448},"tools\u002Fskill-and-tool-validator",{"type":56,"value":450},")\nand the placeholder linter. Without it the green-before \u002F\ngreen-after gate cannot run; stop and ask the user to install\n",{"type":50,"tag":84,"props":452,"children":454},{"className":453},[],[455],{"type":56,"value":436},{"type":56,"value":218},{"type":50,"tag":275,"props":458,"children":459},{},[460,469,471,477,479,485],{"type":50,"tag":64,"props":461,"children":462},{},[463],{"type":50,"tag":84,"props":464,"children":466},{"className":465},[],[467],{"type":56,"value":468},"git",{"type":56,"value":470}," — the behavior-preservation checks rely on\n",{"type":50,"tag":84,"props":472,"children":474},{"className":473},[],[475],{"type":56,"value":476},"git diff",{"type":56,"value":478}," \u002F ",{"type":50,"tag":84,"props":480,"children":482},{"className":481},[],[483],{"type":56,"value":484},"git mv",{"type":56,"value":486},"; the skill expects a clean (or\nintentionally dirty, user-acknowledged) working tree so its own\nedits are isolable.",{"type":50,"tag":275,"props":488,"children":489},{},[490,499],{"type":50,"tag":64,"props":491,"children":492},{},[493],{"type":50,"tag":84,"props":494,"children":496},{"className":495},[],[497],{"type":56,"value":498},"doctoc",{"type":56,"value":500}," — regenerates a sibling\u002Fanchor TOC after a split\nchanges headings. If absent, surface the manual TOC step instead\nof silently skipping it.",{"type":50,"tag":144,"props":502,"children":503},{},[],{"type":50,"tag":148,"props":505,"children":507},{"id":506},"step-0-pre-flight-check",[508],{"type":56,"value":509},"Step 0 — Pre-flight check",{"type":50,"tag":511,"props":512,"children":513},"ol",{},[514,531,548,558],{"type":50,"tag":275,"props":515,"children":516},{},[517,522,524,529],{"type":50,"tag":64,"props":518,"children":519},{},[520],{"type":56,"value":521},"Target resolves",{"type":56,"value":523}," to a real skill directory containing a\n",{"type":50,"tag":84,"props":525,"children":527},{"className":526},[],[528],{"type":56,"value":89},{"type":56,"value":530},". A bad name → stop and list the available skills.",{"type":50,"tag":275,"props":532,"children":533},{},[534,539,541,546],{"type":50,"tag":64,"props":535,"children":536},{},[537],{"type":56,"value":538},"Baseline is green.",{"type":56,"value":540}," Run the validator on the target (or the\nwhole tree for a sweep) and record the result. If it is already\n",{"type":50,"tag":64,"props":542,"children":543},{},[544],{"type":56,"value":545},"red",{"type":56,"value":547},", stop: optimization is a no-behavior-change operation\nlayered on a passing skill, not a way to fix a broken one. Hand\nthe failures back; the maintainer fixes correctness first.",{"type":50,"tag":275,"props":549,"children":550},{},[551,556],{"type":50,"tag":64,"props":552,"children":553},{},[554],{"type":56,"value":555},"Working tree is isolable.",{"type":56,"value":557}," Prefer a clean tree, or a\ndedicated branch, so the optimization diff is reviewable on its\nown. If the tree carries unrelated changes, surface them and ask\nbefore proceeding.",{"type":50,"tag":275,"props":559,"children":560},{},[561,566,568,573],{"type":50,"tag":64,"props":562,"children":563},{},[564],{"type":56,"value":565},"Snapshot is current",{"type":56,"value":567}," (see ",{"type":50,"tag":569,"props":570,"children":571},"em",{},[572],{"type":56,"value":227},{"type":56,"value":574}," above) — a stale\nsnapshot means the target on disk may not match the framework\nthe maintainer thinks they are editing.",{"type":50,"tag":144,"props":576,"children":577},{},[],{"type":50,"tag":148,"props":579,"children":581},{"id":580},"step-1-diagnose",[582],{"type":56,"value":583},"Step 1 — Diagnose",{"type":50,"tag":58,"props":585,"children":586},{},[587,589,597,599,605,607,612],{"type":56,"value":588},"Run every diagnostic in ",{"type":50,"tag":106,"props":590,"children":591},{"href":134},[592],{"type":50,"tag":84,"props":593,"children":595},{"className":594},[],[596],{"type":56,"value":134},{"type":56,"value":598}," against the\ntarget and emit a findings table — one row per detected smell, each\nnaming the pass that addresses it, the evidence (",{"type":50,"tag":84,"props":600,"children":602},{"className":601},[],[603],{"type":56,"value":604},"path:line",{"type":56,"value":606},", line\ncount, the offending construct), and an effort\u002Fblast-radius note.\nDiagnosis is ",{"type":50,"tag":64,"props":608,"children":609},{},[610],{"type":56,"value":611},"read-only",{"type":56,"value":613},"; it never edits.",{"type":50,"tag":58,"props":615,"children":616},{},[617],{"type":56,"value":618},"The five smells, in the order the passes below apply them:",{"type":50,"tag":511,"props":620,"children":621},{},[622,645,676,692,708],{"type":50,"tag":275,"props":623,"children":624},{},[625,630,631,636,638,643],{"type":50,"tag":64,"props":626,"children":627},{},[628],{"type":56,"value":629},"Oversized body",{"type":56,"value":82},{"type":50,"tag":84,"props":632,"children":634},{"className":633},[],[635],{"type":56,"value":89},{"type":56,"value":637}," over the 500-line P14 cap, or a\nsingle section that dominates the body. → ",{"type":50,"tag":569,"props":639,"children":640},{},[641],{"type":56,"value":642},"split",{"type":56,"value":644}," pass.",{"type":50,"tag":275,"props":646,"children":647},{},[648,653,655,661,663,668,670,675],{"type":50,"tag":64,"props":649,"children":650},{},[651],{"type":56,"value":652},"Concrete-name leakage",{"type":56,"value":654}," — adopter-specific values (a concrete\n",{"type":50,"tag":84,"props":656,"children":658},{"className":657},[],[659],{"type":56,"value":660},"\u003Cupstream>",{"type":56,"value":662}," repo slug, real list addresses, real IDs) baked into\nthe body instead of resolved from ",{"type":50,"tag":84,"props":664,"children":666},{"className":665},[],[667],{"type":56,"value":97},{"type":56,"value":669},". →\n",{"type":50,"tag":569,"props":671,"children":672},{},[673],{"type":56,"value":674},"config-lift",{"type":56,"value":644},{"type":50,"tag":275,"props":677,"children":678},{},[679,684,686,691],{"type":50,"tag":64,"props":680,"children":681},{},[682],{"type":56,"value":683},"In-context bulk read",{"type":56,"value":685}," — a step that pulls a whole issue body,\nrollup comment, or large artefact into the agent context only to\ntouch one field of it. → ",{"type":50,"tag":569,"props":687,"children":688},{},[689],{"type":56,"value":690},"out-of-context",{"type":56,"value":644},{"type":50,"tag":275,"props":693,"children":694},{},[695,700,702,707],{"type":50,"tag":64,"props":696,"children":697},{},[698],{"type":56,"value":699},"Per-item round-trips",{"type":56,"value":701}," — N sequential fetches the skill could\nissue as one upfront batch. → ",{"type":50,"tag":569,"props":703,"children":704},{},[705],{"type":56,"value":706},"fetch-upfront",{"type":56,"value":644},{"type":50,"tag":275,"props":709,"children":710},{},[711,716,718,723],{"type":50,"tag":64,"props":712,"children":713},{},[714],{"type":56,"value":715},"No deterministic pre-filter",{"type":56,"value":717}," — the skill spends an LLM pass on\nitems a cheap deterministic classifier could skip as obvious\nno-ops. → ",{"type":50,"tag":569,"props":719,"children":720},{},[721],{"type":56,"value":722},"preflight-classifier",{"type":56,"value":644},{"type":50,"tag":58,"props":725,"children":726},{},[727],{"type":56,"value":728},"For a sweep, rank targets by (cap overflow × number of distinct\nsmells) and present the list; apply nothing until the maintainer\npicks one.",{"type":50,"tag":144,"props":730,"children":731},{},[],{"type":50,"tag":148,"props":733,"children":735},{"id":734},"step-2-propose",[736],{"type":56,"value":737},"Step 2 — Propose",{"type":50,"tag":58,"props":739,"children":740},{},[741,743,748,750,755,757,765],{"type":56,"value":742},"For the chosen target, propose the applicable passes ",{"type":50,"tag":64,"props":744,"children":745},{},[746],{"type":56,"value":747},"in the order\nabove",{"type":56,"value":749}," (lowest blast radius first: a pure file move before any\ncontent lift before any tool rewire). For each proposed pass state:\nthe exact files created\u002Fmoved, the slimming delta (e.g. ",{"type":50,"tag":569,"props":751,"children":752},{},[753],{"type":56,"value":754},"\"SKILL.md\n3425 → ~660 lines, four new siblings\"",{"type":56,"value":756},"), and the\nbehavior-preservation guarantee from ",{"type":50,"tag":106,"props":758,"children":759},{"href":134},[760],{"type":50,"tag":84,"props":761,"children":763},{"className":762},[],[764],{"type":56,"value":134},{"type":56,"value":218},{"type":50,"tag":58,"props":767,"children":768},{},[769],{"type":56,"value":770},"Propose; do not apply. Wait for the maintainer to pick which passes\nto run, in which order.",{"type":50,"tag":144,"props":772,"children":773},{},[],{"type":50,"tag":148,"props":775,"children":777},{"id":776},"step-3-apply-one-pass-at-a-time",[778],{"type":56,"value":779},"Step 3 — Apply one pass at a time",{"type":50,"tag":58,"props":781,"children":782},{},[783],{"type":56,"value":784},"For each confirmed pass, smallest reversible step first:",{"type":50,"tag":271,"props":786,"children":787},{},[788,812],{"type":50,"tag":275,"props":789,"children":790},{},[791,796,798,803,805,810],{"type":50,"tag":64,"props":792,"children":793},{},[794],{"type":56,"value":795},"Restructure passes (split, config-lift)",{"type":56,"value":797}," move or relocate text\nwith ",{"type":50,"tag":64,"props":799,"children":800},{},[801],{"type":56,"value":802},"no wording change to the instructions themselves",{"type":56,"value":804},". Use\n",{"type":50,"tag":84,"props":806,"children":808},{"className":807},[],[809],{"type":56,"value":484},{"type":56,"value":811}," where a whole file relocates; otherwise cut-and-paste the\nexact bytes and replace the body region with a one-line pointer to\nthe new sibling. Never paraphrase a moved instruction — a\nbehavior-preserving move means the moved bytes are identical.",{"type":50,"tag":275,"props":813,"children":814},{},[815,820,822,827,829,834,836,846,848,858],{"type":50,"tag":64,"props":816,"children":817},{},[818],{"type":56,"value":819},"Rewire passes (out-of-context, fetch-upfront,\npreflight-classifier)",{"type":56,"value":821}," change ",{"type":50,"tag":569,"props":823,"children":824},{},[825],{"type":56,"value":826},"how",{"type":56,"value":828}," a step runs, not ",{"type":50,"tag":569,"props":830,"children":831},{},[832],{"type":56,"value":833},"what\ndecision it reaches",{"type":56,"value":835},". They route through an existing deterministic\ntool (e.g. ",{"type":50,"tag":106,"props":837,"children":839},{"href":838},"..\u002F..\u002Ftools\u002Fgithub-body-field\u002FREADME.md",[840],{"type":50,"tag":84,"props":841,"children":843},{"className":842},[],[844],{"type":56,"value":845},"github-body-field",{"type":56,"value":847},",\n",{"type":50,"tag":106,"props":849,"children":851},{"href":850},"..\u002F..\u002Ftools\u002Fgithub-rollup\u002FREADME.md",[852],{"type":50,"tag":84,"props":853,"children":855},{"className":854},[],[856],{"type":56,"value":857},"github-rollup",{"type":56,"value":859},") or a\npre-flight classifier; the human-visible proposals and gates the\nskill produces are unchanged. If a rewire would alter what the\nskill proposes to the user, it is a behavior change — stop and\nroute it through normal review, not this skill.",{"type":50,"tag":58,"props":861,"children":862},{},[863,865,870],{"type":56,"value":864},"After each pass: regenerate the doctoc TOC if headings moved, and\nre-run the validator. One pass per commit keeps the diff reviewable\nand the ",{"type":50,"tag":84,"props":866,"children":868},{"className":867},[],[869],{"type":56,"value":484},{"type":56,"value":871}," rename-detection intact.",{"type":50,"tag":144,"props":873,"children":874},{},[],{"type":50,"tag":148,"props":876,"children":878},{"id":877},"step-4-validate-green-after-gate",[879],{"type":56,"value":880},"Step 4 — Validate (green-after gate)",{"type":50,"tag":58,"props":882,"children":883},{},[884,886,891],{"type":56,"value":885},"Re-run the validator (and the placeholder linter for tracker-\ntouching skills) on the optimized target. It ",{"type":50,"tag":64,"props":887,"children":888},{},[889],{"type":56,"value":890},"must",{"type":56,"value":892}," return the\nsame green it returned at Step 0. Then prove behavior preservation:",{"type":50,"tag":271,"props":894,"children":895},{},[896,922],{"type":50,"tag":275,"props":897,"children":898},{},[899,901,906,908,913,915,920],{"type":56,"value":900},"For restructure passes, confirm the concatenation of ",{"type":50,"tag":84,"props":902,"children":904},{"className":903},[],[905],{"type":56,"value":89},{"type":56,"value":907}," +\nnew siblings contains the same instruction bytes as the original\n(a moved-not-changed check: ",{"type":50,"tag":84,"props":909,"children":911},{"className":910},[],[912],{"type":56,"value":476},{"type":56,"value":914}," should show deletions in\n",{"type":50,"tag":84,"props":916,"children":918},{"className":917},[],[919],{"type":56,"value":89},{"type":56,"value":921}," matching additions in the siblings, plus the new\npointer lines).",{"type":50,"tag":275,"props":923,"children":924},{},[925],{"type":56,"value":926},"For rewire passes, confirm the skill's proposal\u002Fapply surface —\nthe things a human signs off on — is unchanged; only the\nin-context cost or round-trip count drops.",{"type":50,"tag":58,"props":928,"children":929},{},[930,932,937],{"type":56,"value":931},"If the validator goes red or behavior preservation cannot be shown,\n",{"type":50,"tag":64,"props":933,"children":934},{},[935],{"type":56,"value":936},"revert the pass",{"type":56,"value":938}," and hand back; do not ship a half-applied\noptimization.",{"type":50,"tag":144,"props":940,"children":941},{},[],{"type":50,"tag":148,"props":943,"children":945},{"id":944},"step-5-hand-back",[946],{"type":56,"value":947},"Step 5 — Hand back",{"type":50,"tag":58,"props":949,"children":950},{},[951,953,958,960,966,968,973],{"type":56,"value":952},"Summarise per pass: files touched, the slimming delta, validator\nresult, and the behavior-preservation evidence. Do ",{"type":50,"tag":64,"props":954,"children":955},{},[956],{"type":56,"value":957},"not",{"type":56,"value":959}," open a\nPR or commit unless the maintainer asks — surface the diff and let\nthem review. When they do commit, one pass per commit, subject in\nthe ",{"type":50,"tag":84,"props":961,"children":963},{"className":962},[],[964],{"type":56,"value":965},"refactor(\u003Cskill>): …",{"type":56,"value":967}," form the security-suite splits used\n(e.g. ",{"type":50,"tag":569,"props":969,"children":970},{},[971],{"type":56,"value":972},"\"extract N subdocs to slim SKILL.md A → B lines\"",{"type":56,"value":974},").",{"type":50,"tag":58,"props":976,"children":977},{},[978],{"type":56,"value":979},"If the run was a sweep, restate the ranked remaining candidates so\nthe maintainer can queue the next one.",{"type":50,"tag":144,"props":981,"children":982},{},[],{"type":50,"tag":148,"props":984,"children":986},{"id":985},"hard-rules",[987],{"type":56,"value":988},"Hard rules",{"type":50,"tag":271,"props":990,"children":991},{},[992,1002,1012,1022,1032,1042],{"type":50,"tag":275,"props":993,"children":994},{},[995,1000],{"type":50,"tag":64,"props":996,"children":997},{},[998],{"type":56,"value":999},"Behavior never changes.",{"type":56,"value":1001}," This skill restructures and rewires;\nit never alters what a skill decides, proposes, or asks a human to\nconfirm. A change that alters behavior is out of scope — route it\nthrough normal skill editing and review.",{"type":50,"tag":275,"props":1003,"children":1004},{},[1005,1010],{"type":50,"tag":64,"props":1006,"children":1007},{},[1008],{"type":56,"value":1009},"Moved bytes are identical bytes.",{"type":56,"value":1011}," A split or lift that\nparaphrases the moved instructions is a behavior change in\ndisguise. Move verbatim; only the surrounding pointer is new.",{"type":50,"tag":275,"props":1013,"children":1014},{},[1015,1020],{"type":50,"tag":64,"props":1016,"children":1017},{},[1018],{"type":56,"value":1019},"Propose before applying.",{"type":56,"value":1021}," Every pass is a proposal the\nmaintainer confirms (framework Principle 6). Never batch-apply a\nsweep.",{"type":50,"tag":275,"props":1023,"children":1024},{},[1025,1030],{"type":50,"tag":64,"props":1026,"children":1027},{},[1028],{"type":56,"value":1029},"The validator is the gate.",{"type":56,"value":1031}," Green before, green after, every\npass. A pass that needs the validator relaxed is not an\noptimization.",{"type":50,"tag":275,"props":1033,"children":1034},{},[1035,1040],{"type":50,"tag":64,"props":1036,"children":1037},{},[1038],{"type":56,"value":1039},"The optimized SKILL.md still obeys P14",{"type":56,"value":1041}," — under 500 lines, with\nevery sibling linked exactly one level deep and no unreferenced\nsiblings.",{"type":50,"tag":275,"props":1043,"children":1044},{},[1045,1050,1052,1057,1059,1064],{"type":50,"tag":64,"props":1046,"children":1047},{},[1048],{"type":56,"value":1049},"Never touch the snapshot",{"type":56,"value":1051}," (",{"type":50,"tag":84,"props":1053,"children":1055},{"className":1054},[],[1056],{"type":56,"value":208},{"type":56,"value":1058},").\nFramework-skill optimizations land via PR to ",{"type":50,"tag":84,"props":1060,"children":1062},{"className":1061},[],[1063],{"type":56,"value":216},{"type":56,"value":218},{"type":50,"tag":144,"props":1066,"children":1067},{},[],{"type":50,"tag":148,"props":1069,"children":1071},{"id":1070},"references",[1072],{"type":56,"value":1073},"References",{"type":50,"tag":271,"props":1075,"children":1076},{},[1077,1090,1103,1116,1141],{"type":50,"tag":275,"props":1078,"children":1079},{},[1080,1088],{"type":50,"tag":106,"props":1081,"children":1082},{"href":134},[1083],{"type":50,"tag":84,"props":1084,"children":1086},{"className":1085},[],[1087],{"type":56,"value":134},{"type":56,"value":1089}," — the five optimization passes:\nsmell, exemplar PR, mechanics, behavior-preservation guarantee,\nvalidation.",{"type":50,"tag":275,"props":1091,"children":1092},{},[1093,1101],{"type":50,"tag":106,"props":1094,"children":1095},{"href":108},[1096],{"type":50,"tag":84,"props":1097,"children":1099},{"className":1098},[],[1100],{"type":56,"value":115},{"type":56,"value":1102}," — authoring a net-new\nskill (this skill's counterpart).",{"type":50,"tag":275,"props":1104,"children":1105},{},[1106,1114],{"type":50,"tag":106,"props":1107,"children":1108},{"href":441},[1109],{"type":50,"tag":84,"props":1110,"children":1112},{"className":1111},[],[1113],{"type":56,"value":448},{"type":56,"value":1115},"\n— the green-before \u002F green-after gate.",{"type":50,"tag":275,"props":1117,"children":1118},{},[1119,1128,1130,1139],{"type":50,"tag":106,"props":1120,"children":1121},{"href":838},[1122],{"type":50,"tag":84,"props":1123,"children":1125},{"className":1124},[],[1126],{"type":56,"value":1127},"tools\u002Fgithub-body-field",{"type":56,"value":1129},"\nand ",{"type":50,"tag":106,"props":1131,"children":1132},{"href":850},[1133],{"type":50,"tag":84,"props":1134,"children":1136},{"className":1135},[],[1137],{"type":56,"value":1138},"tools\u002Fgithub-rollup",{"type":56,"value":1140},"\n— out-of-context read\u002FPATCH tools the rewire passes route through.",{"type":50,"tag":275,"props":1142,"children":1143},{},[1144,1154,1156,1162],{"type":50,"tag":106,"props":1145,"children":1147},{"href":1146},"..\u002F..\u002Fdocs\u002Flabels-and-capabilities.md",[1148],{"type":50,"tag":84,"props":1149,"children":1151},{"className":1150},[],[1152],{"type":56,"value":1153},"docs\u002Flabels-and-capabilities.md",{"type":56,"value":1155},"\n— the ",{"type":50,"tag":84,"props":1157,"children":1159},{"className":1158},[],[1160],{"type":56,"value":1161},"capability:*",{"type":56,"value":1163}," taxonomy and the P14 authorship rule this\nskill enforces.",{"items":1165,"total":1318},[1166,1184,1200,1211,1224,1237,1255,1266,1276,1287,1297,1307],{"slug":1167,"name":1167,"fn":1168,"description":1169,"org":1170,"tags":1171,"stars":1181,"repoUrl":1182,"updatedAt":1183},"datafusion-python","write Apache DataFusion Python code","Use when the user is writing datafusion-python (Apache DataFusion Python bindings) DataFrame or SQL code. Covers imports, data loading, DataFrame operations, expression building, SQL-to-DataFrame mappings, idiomatic patterns, and common pitfalls.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1172,1175,1178],{"name":1173,"slug":1174,"type":15},"Data Analysis","data-analysis",{"name":1176,"slug":1177,"type":15},"Python","python",{"name":1179,"slug":1180,"type":15},"SQL","sql",593,"https:\u002F\u002Fgithub.com\u002Fapache\u002Fdatafusion-python","2026-07-12T08:36:04.957626",{"slug":1185,"name":1185,"fn":1186,"description":1187,"org":1188,"tags":1189,"stars":1197,"repoUrl":1198,"updatedAt":1199},"bydbql","generate and execute BanyanDB BydbQL queries","Generate, validate, and optionally execute read-only BanyanDB BydbQL for STREAM, MEASURE, TRACE, and PROPERTY resources. Use when the user asks to query BanyanDB, translate natural language to BydbQL, inspect BanyanDB schema or data, validate BydbQL, or fetch raw BanyanDB records.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1190,1193,1196],{"name":1191,"slug":1192,"type":15},"Analytics","analytics",{"name":1194,"slug":1195,"type":15},"Database","database",{"name":1179,"slug":1180,"type":15},344,"https:\u002F\u002Fgithub.com\u002Fapache\u002Fskywalking-banyandb","2026-07-12T08:31:01.294423",{"slug":1201,"name":1201,"fn":1202,"description":1203,"org":1204,"tags":1205,"stars":1197,"repoUrl":1198,"updatedAt":1210},"compiling","compile and build BanyanDB projects","Compile and build the SkyWalking BanyanDB project. Use when the user asks to compile, build, or generate code for this project.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1206,1209],{"name":1207,"slug":1208,"type":15},"Build","build",{"name":17,"slug":18,"type":15},"2026-07-12T08:31:06.373309",{"slug":1212,"name":1212,"fn":1213,"description":1214,"org":1215,"tags":1216,"stars":1197,"repoUrl":1198,"updatedAt":1223},"gh-pull-request","create GitHub pull requests for BanyanDB","Create a GitHub pull request for SkyWalking BanyanDB. Use when the user asks to create a PR, submit changes, or open a pull request.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1217,1220],{"name":1218,"slug":1219,"type":15},"GitHub","github",{"name":1221,"slug":1222,"type":15},"Pull Requests","pull-requests","2026-07-12T08:31:03.792415",{"slug":1225,"name":1225,"fn":1226,"description":1227,"org":1228,"tags":1229,"stars":1197,"repoUrl":1198,"updatedAt":1236},"vendor-update","update Go and Node.js vendor dependencies","Upgrade Go\u002FNode.js vendor dependencies and sync tool versions. Use whenever the user says \"upgrade dependencies\", \"update vendors\", \"vendor update\", \"run vendor-upgrade\", \"bump dependencies\", \"update packages\", or asks to run the `vendor-update` Make target. This skill also checks `scripts\u002Fbuild\u002Fversion.mk` after upgrading to see if any tracked tool versions need updating too, and removes stale binaries from `bin\u002F` when versions change.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1230,1233],{"name":1231,"slug":1232,"type":15},"Go","go",{"name":1234,"slug":1235,"type":15},"Node.js","node-js","2026-07-12T08:31:02.555555",{"slug":1238,"name":1238,"fn":1239,"description":1240,"org":1241,"tags":1242,"stars":1252,"repoUrl":1253,"updatedAt":1254},"cayenne-cgen","generate Cayenne entity Java classes","Use this skill whenever the user wants to (re)generate Cayenne entity Java classes from a DataMap. Trigger on phrases like 'generate Java classes', 'regenerate entities', 'run cgen', 'create the entity classes', 'why is the Artist class missing fields', 'where did the `_Abstract*` classes come from', 'sync the entity classes with the model', or any request to materialize Java from the DataMap. Also trigger as a follow-up after modeling changes (someone added an entity, attribute, or relationship and now the Java side is stale). This skill exclusively uses the `mcp__cayenne__cgen_run` MCP tool — it does NOT use `mvn cayenne:cgen` or the Gradle cgen task.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1243,1246,1249],{"name":1244,"slug":1245,"type":15},"Data Modeling","data-modeling",{"name":1247,"slug":1248,"type":15},"Java","java",{"name":1250,"slug":1251,"type":15},"ORM","orm",343,"https:\u002F\u002Fgithub.com\u002Fapache\u002Fcayenne","2026-07-12T08:32:33.575211",{"slug":1256,"name":1256,"fn":1257,"description":1258,"org":1259,"tags":1260,"stars":1252,"repoUrl":1253,"updatedAt":1265},"cayenne-db-import","import database schema into Cayenne DataMaps","Use this skill when the user wants to import database schema metadata into a Cayenne DataMap — the *model\u002Fmapping only*, not names or Java classes. Trigger on phrases like 'reverse engineer the database', 'import the schema', 'generate a DataMap from my DB', 'add the new tables from the DB into the model', 'import the customer table', 'create entities from these tables', or any request to read database metadata to populate or update a DataMap's XML. This is for *full schema* or *bulk table* import; one-off a-la-carte entity additions belong in the cayenne-modeling skill. IMPORTANT — scope: this imports the mapping ONLY; it does not clean up the Object-layer names or (re)generate Java classes. When the user wants their whole project brought in line with the DB ('sync my project with the database', 'my schema changed, update everything', 'update my entities\u002Fclasses from the DB'), that is the end-to-end `cayenne-full-db-sync` skill, which runs this import and then name cleanup and class generation. To regenerate classes alone use `cayenne-cgen`. The skill runs reverse engineering directly via the `mcp__cayenne__dbimport_run` MCP tool when a DBConnector is already configured; otherwise it opens the CayenneModeler GUI via `mcp__cayenne__open_project` to configure the connection first.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1261,1262,1263,1264],{"name":1194,"slug":1195,"type":15},{"name":1247,"slug":1248,"type":15},{"name":1250,"slug":1251,"type":15},{"name":1179,"slug":1180,"type":15},"2026-07-19T05:40:33.655062",{"slug":1267,"name":1267,"fn":1268,"description":1269,"org":1270,"tags":1271,"stars":1252,"repoUrl":1253,"updatedAt":1275},"cayenne-full-db-sync","synchronize Cayenne projects with database","Use this skill when the user wants to bring their WHOLE Cayenne project in line with the database in one shot — the mapping, the Object-layer names, and the generated Java classes together. This is the end-to-end 'sync with the DB' workflow, and it orchestrates three skills in order: `cayenne-db-import` (import schema metadata into the DataMap) → `cayenne-model-naming` (polish the just-imported names) → `cayenne-cgen` (regenerate Java classes). Trigger on holistic phrases like 'sync my project with the database', 'sync with the DB', 'my schema changed, update everything', 'update my entities\u002Fclasses from the database', 'reverse engineer and regenerate the classes', 'import the new tables and rebuild the entities', 'full DB sync', 'bring the model and classes up to date with the DB'. The distinguishing signal is scope: the user wants the whole project (mapping + names + Java code), not just one stage. For the *model\u002Fmapping only* (no name cleanup, no class generation) use `cayenne-db-import`; to (re)generate classes alone use `cayenne-cgen`; to clean names alone use `cayenne-model-naming`. Uses the `mcp__cayenne__dbimport_run` and `mcp__cayenne__cgen_run` MCP tools via the sub-skills; does NOT use Maven or Gradle goals.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1272,1273,1274],{"name":1194,"slug":1195,"type":15},{"name":1247,"slug":1248,"type":15},{"name":1250,"slug":1251,"type":15},"2026-07-19T06:03:49.112969",{"slug":1277,"name":1277,"fn":1278,"description":1279,"org":1280,"tags":1281,"stars":1252,"repoUrl":1253,"updatedAt":1286},"cayenne-model-naming","clean up Cayenne object-layer names","Use this skill to clean up Object-layer names in a Cayenne DataMap — ObjEntity, ObjAttribute, and ObjRelationship names, plus DbRelationship names (the first-class unit of relationship cleanup — every FK has one whether or not an ObjRelationship was generated; the ObjRelationship name is synced to it when one exists) — so they read as descriptive, consistent Java. Trigger on phrases like 'clean up the model names', 'fix the entity names', 'these names look ugly', 'make the names descriptive', 'normalize the ObjEntity\u002Fattribute\u002Frelationship names', 'why is this relationship called team1', 'rename entities to be consistent', 'the import produced Gametype instead of GameType'. Invoke it on an explicit user request, or as a manual follow-up after a `cayenne-db-import` to polish the just-imported additions — it is never triggered automatically. IMPORTANT: this is a LIGHT polish pass — CayenneModeler's reverse-engineering already produces good names for the common case; only improve the specific things its deterministic algorithm cannot (run-together names with no separators like `gametype`, meaningless numbered names like `team1` from multiple relationships between two tables, and a common entity prefix that leaks into relationship names like `aaOrders`). Do NOT rewrite names that are already correct. This is Obj-layer naming polish; for structural model edits use `cayenne-modeling`, and for regenerating classes afterward use `cayenne-cgen`.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1282,1283,1284,1285],{"name":1244,"slug":1245,"type":15},{"name":1194,"slug":1195,"type":15},{"name":1247,"slug":1248,"type":15},{"name":1250,"slug":1251,"type":15},"2026-07-22T05:35:32.342548",{"slug":1288,"name":1288,"fn":1289,"description":1290,"org":1291,"tags":1292,"stars":1252,"repoUrl":1253,"updatedAt":1296},"cayenne-modeler","manage Cayenne projects with CayenneModeler","Use this skill when the user explicitly wants to open CayenneModeler (the GUI) on a Cayenne project, or when the modeling task is inherently visual — reverse engineering (delegated to cayenne-db-import), bulk relationship layout, multi-entity visual refactoring. Trigger on phrases like 'open the Modeler', 'open in CayenneModeler', 'launch the GUI', 'edit visually', 'show me the project in the Modeler'. Do NOT trigger as a fallback for ordinary a-la-carte XML edits — those belong in the cayenne-modeling skill, which is faster and doesn't require the user to context-switch.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1293,1294,1295],{"name":1244,"slug":1245,"type":15},{"name":1247,"slug":1248,"type":15},{"name":1250,"slug":1251,"type":15},"2026-07-12T08:32:37.199428",{"slug":1298,"name":1298,"fn":1299,"description":1300,"org":1301,"tags":1302,"stars":1252,"repoUrl":1253,"updatedAt":1306},"cayenne-modeling","edit and extend Cayenne ORM models","Use this skill whenever the user wants to edit, inspect, or extend the Cayenne ORM model in a project — adding or modifying entities, attributes, relationships, embeddables, named queries, stored procedures, or DataNodes. Trigger on phrases like 'add an ObjEntity', 'add a DbEntity', 'add a relationship', 'expose this column as an attribute', 'create a new DataMap', 'add a named query', 'create an embeddable', 'add a stored procedure', 'change the attribute type', 'mark this column as nullable', 'rename this entity', or any mention of a Cayenne `*.map.xml` or `cayenne-*.xml` file. Also trigger when the user references modeling concepts (ObjEntity, DbEntity, ObjAttribute, DbAttribute, ObjRelationship, DbRelationship, Embeddable, dbEntityName, deleteRule, db-attribute-path, db-relationship-path, defaultPackage) in the context of a Cayenne-using app. This is the *primary* skill for a-la-carte ORM model manipulation — direct XML edits, not the Modeler GUI.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1303,1304,1305],{"name":1194,"slug":1195,"type":15},{"name":1247,"slug":1248,"type":15},{"name":1250,"slug":1251,"type":15},"2026-07-19T05:40:32.6889",{"slug":1308,"name":1308,"fn":1309,"description":1310,"org":1311,"tags":1312,"stars":1252,"repoUrl":1253,"updatedAt":1317},"cayenne-query","write and modify Cayenne database queries","Use this skill whenever the user wants to write or modify a Cayenne query — fetching entities by criteria, joining, prefetching to avoid N+1, ordering, paginating, aggregating, or running raw SQL through Cayenne. Trigger on phrases like 'query for X', 'fetch all artists where ...', 'write an ObjectSelect', 'use SQLSelect', 'use SelectById', 'add a prefetch', 'get distinct values', 'count rows', 'find by ID', 'load by primary key', 'build a Cayenne expression', 'why am I getting N+1', 'how do I paginate', 'select a single column', 'select columns into a DTO', 'named query in the DataMap'. Do NOT trigger for modeling changes (use cayenne-modeling) or runtime bootstrap (use cayenne-runtime).",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1313,1314,1315,1316],{"name":1194,"slug":1195,"type":15},{"name":1247,"slug":1248,"type":15},{"name":1250,"slug":1251,"type":15},{"name":1179,"slug":1180,"type":15},"2026-07-12T08:32:35.072322",108,{"items":1320,"total":1415},[1321,1334,1350,1364,1380,1392,1402],{"slug":1322,"name":1322,"fn":1323,"description":1324,"org":1325,"tags":1326,"stars":22,"repoUrl":23,"updatedAt":1333},"generate-cve-json","generate CVE JSON documents","Generate a CVE 5.x JSON document from an \u003Ctracker> tracking\nissue, ready to paste into the Vulnogram `#source` tab of the ASF CVE tool\nat https:\u002F\u002Fcveprocess.apache.org\u002Fcve5\u002F\u003CCVE-ID>#source. The conversion is\ndeterministic: same issue in, same JSON bytes out. Handles multiple\ncredits (one per line) and multiple references (URLs extracted from the\nissue's \"Public advisory URL\" and \"PR with the fix\" fields; the\n\"Security mailing list thread\" field is treated as internal-only and\nnever exported).\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1327,1330,1332],{"name":1328,"slug":1329,"type":15},"Compliance","compliance",{"name":1331,"slug":32,"type":15},"Security",{"name":20,"slug":21,"type":15},"2026-07-12T08:35:41.218722",{"slug":1335,"name":1335,"fn":1336,"description":1337,"org":1338,"tags":1339,"stars":22,"repoUrl":23,"updatedAt":1349},"magpie-audit-finding-fix","fix findings from code audit tools","For a batch of findings from a non-security audit tool\n(`\u003Caudit-tool>` — ruff \u002F flake8 \u002F mypy \u002F pylint \u002F CodeQL \u002F\nApache Verum \u002F Apache Caer \u002F equivalent; full list in the body)\nagainst `\u003Cupstream>`, draft the smallest fix for each finding.\nRe-runs the tool after each batch to confirm the findings are\ncleared. Produces a commit and a hand-back artefact; never opens\na PR on autopilot or merges.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1340,1343,1346],{"name":1341,"slug":1342,"type":15},"Audit","audit",{"name":1344,"slug":1345,"type":15},"Code Analysis","code-analysis",{"name":1347,"slug":1348,"type":15},"Debugging","debugging","2026-07-12T08:35:13.930479",{"slug":1351,"name":1351,"fn":1352,"description":1353,"org":1354,"tags":1355,"stars":22,"repoUrl":23,"updatedAt":1363},"magpie-ci-runner-audit","audit GitHub Actions workflow runner compatibility","Read-only audit of GitHub Actions workflow runner compatibility\nfor one repository, an explicit repository set, one Apache project\nwith multiple repositories, or the full Apache GitHub org. Finds\nobsolete GitHub-hosted runner labels and macOS runner\u002Ftool\narchitecture mismatches. Produces TSV evidence files; never edits\nworkflows, opens PRs, or posts comments.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1356,1357,1360],{"name":1341,"slug":1342,"type":15},{"name":1358,"slug":1359,"type":15},"CI\u002FCD","ci-cd",{"name":1361,"slug":1362,"type":15},"GitHub Actions","github-actions","2026-07-12T08:34:30.320965",{"slug":1365,"name":1365,"fn":1366,"description":1367,"org":1368,"tags":1369,"stars":22,"repoUrl":23,"updatedAt":1379},"magpie-committer-onboarding","onboard Apache project committers","Post-vote committer and PMC onboarding for Apache projects.\nWalks the nominator through every step from ICLA check to\nwelcome announcement for both incubating podlings and\ngraduated top-level projects.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1370,1373,1376],{"name":1371,"slug":1372,"type":15},"Management","management",{"name":1374,"slug":1375,"type":15},"Operations","operations",{"name":1377,"slug":1378,"type":15},"Process Documentation","process-documentation","2026-07-12T08:33:35.628029",{"slug":1381,"name":1381,"fn":1382,"description":1383,"org":1384,"tags":1385,"stars":22,"repoUrl":23,"updatedAt":1391},"magpie-contributor-activity-sweep","generate contributor activity reports","Read-only GitHub activity card for a named contributor on \u003Cupstream>.\nFetches PR authorship, code-review activity, issues, and PR\u002Fissue\ncomments over a configurable window. Limited to GitHub-visible\nactivity — the body documents the off-GitHub tracks the nominator\nmust supply separately. No readiness verdict is produced; use\ncontributor-nomination for a full nomination brief.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1386,1387,1388],{"name":1191,"slug":1192,"type":15},{"name":1218,"slug":1219,"type":15},{"name":1389,"slug":1390,"type":15},"Reporting","reporting","2026-07-12T08:33:41.715859",{"slug":1393,"name":1393,"fn":1394,"description":1395,"org":1396,"tags":1397,"stars":22,"repoUrl":23,"updatedAt":1401},"magpie-contributor-nomination","generate contributor nomination briefs","Read-only nomination brief for a named GitHub contributor on\n\u003Cupstream>. Aggregates GitHub activity across all contribution\ntracks plus maintainer-supplied off-GitHub signal, and flags\nvendor-neutrality context — the evidence a PMC needs to open\na committer or PMC nomination thread.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1398,1399,1400],{"name":17,"slug":18,"type":15},{"name":1218,"slug":1219,"type":15},{"name":1389,"slug":1390,"type":15},"2026-07-12T08:33:39.211745",{"slug":1403,"name":1403,"fn":1404,"description":1405,"org":1406,"tags":1407,"stars":22,"repoUrl":23,"updatedAt":1414},"magpie-contributor-sentiment","measure contributor sentiment on GitHub repositories","Measures contributor-sentiment signals on \u003Cupstream> over a\nconfigurable window: thread tone (first-response classification),\ntime-to-first-reply (median hours), first-PR retention\n(second-PR rate), and reviewer load (Gini coefficient). Compares\neach signal against a pre-adoption baseline and produces a\nstructured gate report used to decide whether a skill family is\nready to advance from experimental to stable.\n",{"slug":8,"name":9,"logoUrl":10,"githubOrg":8},[1408,1409,1412,1413],{"name":1191,"slug":1192,"type":15},{"name":1410,"slug":1411,"type":15},"Communications","communications",{"name":17,"slug":18,"type":15},{"name":1218,"slug":1219,"type":15},"2026-07-12T08:34:09.204167",71]