Skip to content

perf(setup): trim the setup family skills without changing behaviour - #1353

Merged
potiuk merged 1 commit into
apache:mainfrom
potiuk:optimize-setup-skill
Sep 22, 2026
Merged

potiuk merged 1 commit into
apache:mainfrom
potiuk:optimize-setup-skill

Conversation

@potiuk

@potiuk potiuk commented Sep 22, 2026

Copy link
Copy Markdown
Member

Summary

  • Apply the optimize-skill recipe to the setup family, without changing what any skill does: 31,951 → 29,242 body tokens across seven skills (−8.5%), and the setup frontmatter (loaded in every session) from ~228 to ~167 tokens, under the 200-token budget.
  • Move Golden rules 7 and 9 out of setup/SKILL.md, byte-for-byte, into the sibling files that use them (overrides.md, snapshot-model.md); rule 8 stays because 12 places cite it.
  • Wording pass (one sentence per line, cut restatement) on setup plus isolated-setup-doctor / -verify / -update, upstream-fix, override-upstream and shared-config-sync.
skill before after
setup 4,972 4,187
setup-isolated-setup-verify 4,967 4,556
setup-upstream-fix 4,614 4,245
setup-shared-config-sync 4,185 3,836
setup-isolated-setup-update 4,356 4,017
setup-override-upstream 3,960 3,681
setup-isolated-setup-doctor 4,897 4,720

Type of change

  • Skill change — no eval fixtures changed (no behaviour change)
  • Documentation (docs/mode-economics.md, docs/setup/marketplace.md token figures)

Test plan

  • prek run --all-files passes (validator, lychee, surface-hash, token count, doc-sync)
  • Mechanical invariant check against main for every rewritten file: frontmatter, pre-flight block, fenced code blocks, headings, golden-rule headlines and link targets identical; inline code spans preserved (whitespace-normalised). The only removed span is link text naming the deleted docs/setup/install-recipes.md, now matching its unchanged target.
  • Eval suites for all seven skills, run on this branch and on main (outside the sandbox — the harness's claude -p exits 1 inside it):
suite this branch main
setup 74/83 same failing suites fail or flip on main (preflight-floor 2/8, uninstall-default-set 1/3)
isolated-setup-doctor 22/22 —
isolated-setup-verify 9/14 10/14
isolated-setup-update 14/15 13/15
upstream-fix 8/8 8/8
override-upstream 13/15 14/15
shared-config-sync 12/12 12/12

Every failure on this branch either fails on main too or is non-deterministic: re-running the branch-only failures (verify step-1-classify case-3 / case-6, override-upstream step-0 case-3) passed them, and other cases in those steps failed instead. step-m3 and step-override-bypass extract text this PR does not touch.

RFC-AI-0004 compliance

No behaviour change; every confirmation gate, "never" rule and placeholder is preserved.

Linked issues

Closes #1343. Part of #1342.

Notes for reviewers

  • setup's surface_hash changes (golden-rule callouts are fingerprinted with their file), so adopters who reconciled or overrode setup see one stale-configuration notice. The other six skills' hashes are unchanged.
  • Stale pointers fixed on the way: four rule-6 links aimed at SKILL.md#golden-rules, three link labels naming the deleted install-recipes.md, a doctor cross-reference to the wrong probe, a shared-config-sync pointer to a non-existent golden rule.
  • Eval-coupled inconsistencies found but deliberately left alone are listed in Optimize the setup skill family #1343.

🤖 Generated with Claude Code

Move Golden rules 7 and 9 out of setup/SKILL.md into the sibling files
that use them (overrides.md, snapshot-model.md), byte-for-byte, and
repoint their references. Trim the setup frontmatter under the 200-token
always-on budget. Tighten the prose of setup and six more setup-family
skills to one sentence per line, with headings, golden-rule headlines,
code blocks and pre-flight blocks unchanged.

Fixes stale pointers found on the way: rule 6 links aimed at SKILL.md,
link text naming the removed docs/setup/install-recipes.md, and a
doctor cross-reference to the wrong probe.

Body tokens across the seven skills: 31,951 -> 29,242.

Part of apache#1342.

Generated-by: Claude Opus 5
@potiuk
potiuk merged commit 4bee474 into apache:main Sep 22, 2026
10 checks passed
liwenjie200543 added a commit to liwenjie200543/magpie that referenced this pull request Sep 26, 2026
Body tokens across the eight pr-management skills drop from 54,714 to
34,298 (-37.3%), all inside the 5,000-token body budget and the
500-line cap, with all always-on frontmatter budgets met.

- Trim every skill's frontmatter under the 200-token always-on budget
  (7 of 8 skills were over).
- Move sub-action-specific sections and individual sub-action golden
  rules into sibling files byte-for-byte and repoint their references,
  the same technique as the setup-family PRs (apache#1353): 16 new sibling
  files, no section left in two places.
- Tighten remaining prose to SemBr one-sentence-per-line, keeping
  headings, golden-rule headlines, code blocks, tables and the
  generated pre-flight block byte-identical.
- Fix one stale pointer per the apache#1353 precedent: pr-triage's moved
  Step 6b block in session-history.md anchored [Parameters] at the
  sibling itself.
- Regenerate docs/mode-economics.md via skill-token-count --write.

Verification: skill-token-count --check passes against the regenerated
table; all 22 eval step-config.json extraction targets across the
suites touching this family resolve to their exact heading in the
exact file they point to; check-shared-blocks in sync across all 65
skills; check-duplication reports 0 pairs above the fail threshold;
skill-evals pytest runs 174 tests with no new failures vs the
untouched baseline; skill-and-tool-validate reports no findings in
the touched plugin.

Closes apache#1346. Part of apache#1342.

Generated-by: GLM-5.3-Flash
liwenjie200543 added a commit to liwenjie200543/magpie that referenced this pull request Sep 26, 2026
Body tokens across the eight pr-management skills drop from 54,714 to
34,298 (-37.3%), all inside the 5,000-token body budget and the
500-line cap, with all always-on frontmatter budgets met.

- Trim every skill's frontmatter under the 200-token always-on budget
  (7 of 8 skills were over).
- Move sub-action-specific sections and individual sub-action golden
  rules into sibling files byte-for-byte and repoint their references,
  the same technique as the setup-family PRs (apache#1353): 16 new sibling
  files, no section left in two places.
- Tighten remaining prose to SemBr one-sentence-per-line, keeping
  headings, golden-rule headlines, code blocks, tables and the
  generated pre-flight block byte-identical.
- Fix one stale pointer per the apache#1353 precedent: pr-triage's moved
  Step 6b block in session-history.md anchored [Parameters] at the
  sibling itself.
- Regenerate docs/mode-economics.md via skill-token-count --write.

Verification: skill-token-count --check passes against the regenerated
table; all 22 eval step-config.json extraction targets across the
suites touching this family resolve to their exact heading in the
exact file they point to; check-shared-blocks in sync across all 65
skills; check-duplication reports 0 pairs above the fail threshold;
skill-evals pytest runs 174 tests with no new failures vs the
untouched baseline; skill-and-tool-validate reports no findings in
the touched plugin.

Closes apache#1346. Part of apache#1342.

Generated-by: GLM-5.3-Flash
potiuk pushed a commit to liwenjie200543/magpie that referenced this pull request Sep 26, 2026
Body tokens across the eight pr-management skills drop from 54,714 to
34,298 (-37.3%), all inside the 5,000-token body budget and the
500-line cap, with all always-on frontmatter budgets met.

- Trim every skill's frontmatter under the 200-token always-on budget
  (7 of 8 skills were over).
- Move sub-action-specific sections and individual sub-action golden
  rules into sibling files byte-for-byte and repoint their references,
  the same technique as the setup-family PRs (apache#1353): 16 new sibling
  files, no section left in two places.
- Tighten remaining prose to SemBr one-sentence-per-line, keeping
  headings, golden-rule headlines, code blocks, tables and the
  generated pre-flight block byte-identical.
- Fix one stale pointer per the apache#1353 precedent: pr-triage's moved
  Step 6b block in session-history.md anchored [Parameters] at the
  sibling itself.
- Regenerate docs/mode-economics.md via skill-token-count --write.

Verification: skill-token-count --check passes against the regenerated
table; all 22 eval step-config.json extraction targets across the
suites touching this family resolve to their exact heading in the
exact file they point to; check-shared-blocks in sync across all 65
skills; check-duplication reports 0 pairs above the fail threshold;
skill-evals pytest runs 174 tests with no new failures vs the
untouched baseline; skill-and-tool-validate reports no findings in
the touched plugin.

Closes apache#1346. Part of apache#1342.

Generated-by: GLM-5.3-Flash
potiuk added a commit that referenced this pull request Sep 26, 2026
…our (#1390)

* perf(pr-management): trim the family's skills without changing behaviour

Body tokens across the eight pr-management skills drop from 54,714 to
34,298 (-37.3%), all inside the 5,000-token body budget and the
500-line cap, with all always-on frontmatter budgets met.

- Trim every skill's frontmatter under the 200-token always-on budget
  (7 of 8 skills were over).
- Move sub-action-specific sections and individual sub-action golden
  rules into sibling files byte-for-byte and repoint their references,
  the same technique as the setup-family PRs (#1353): 16 new sibling
  files, no section left in two places.
- Tighten remaining prose to SemBr one-sentence-per-line, keeping
  headings, golden-rule headlines, code blocks, tables and the
  generated pre-flight block byte-identical.
- Fix one stale pointer per the #1353 precedent: pr-triage's moved
  Step 6b block in session-history.md anchored [Parameters] at the
  sibling itself.
- Regenerate docs/mode-economics.md via skill-token-count --write.

Verification: skill-token-count --check passes against the regenerated
table; all 22 eval step-config.json extraction targets across the
suites touching this family resolve to their exact heading in the
exact file they point to; check-shared-blocks in sync across all 65
skills; check-duplication reports 0 pairs above the fail threshold;
skill-evals pytest runs 174 tests with no new failures vs the
untouched baseline; skill-and-tool-validate reports no findings in
the touched plugin.

Closes #1346. Part of #1342.

Generated-by: GLM-5.3-Flash

* fix(pr-management): resolve the prek findings from the family trim

- markdownlint: drop a double blank line in pr-triage SKILL.md, insert
  blank lines before thematic breaks that parsed as setext headings
  (quick-merge fetch-and-screen, stats classify/fetch/render), and
  promote the moved Step 6b section to h2 in session-history.md so
  heading levels increment.
- Anchors: repoint six links whose SKILL.md targets moved into sibling
  files (pr-triage actions/classify-and-act/interaction-loop/
  prerequisites, quick-merge present-and-handoff, and the
  projects/_template config), keeping every fragment slug identical.
- docs/setup/marketplace.md: refresh the family's declared always-on
  tokens to ~0.8k after the frontmatter trim.
- Regenerate docs/mode-economics.md and docs/vendor-neutrality.md.

Verification: skill-token-count --check passes; check-shared-blocks in
sync (65 skills); check-duplication 0 pairs above threshold;
skill-evals pytest 174 tests with no new failures vs the untouched
baseline; every eval step-config extraction target still resolves;
all six repointed anchors verified against the headings now holding
them.

Generated-by: GLM-5.3-Flash

* fix(pr-management): keep reviewer-routing's session-scoped confirmation and catch-all trigger

The trim dropped "in this session" from Golden rule 1, loosening the
confirmation requirement, and the "any variation on proposing a first
reviewer" catch-all from when_to_use, which routes paraphrased requests
to the skill. Restore both. Re-stamp measured_tokens after rebasing onto
the per-skill token stamps.

Generated-by: Claude Opus 5

---------

Co-authored-by: Jarek Potiuk <jarek@potiuk.com>
@potiuk potiuk added capability:intake Import external signal + sync tracker state capability:platform Framework / agent substrate skills (install, verify, doctor, override, status, setup bootstrap) capability:reassess Re-run historical issues against current code family:docs Docs, MISSION.md, READMEs family:setup setup-* skills labels Nov 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

capability:intake Import external signal + sync tracker state capability:platform Framework / agent substrate skills (install, verify, doctor, override, status, setup bootstrap) capability:reassess Re-run historical issues against current code family:docs Docs, MISSION.md, READMEs family:setup setup-* skills

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Optimize the setup skill family

1 participant