Skip to content

perf(pairing): trim always-on frontmatter and dedupe body prose - #1475

Merged
onlyarnav merged 1 commit into
apache:mainfrom
liwenjie200543:perf/pairing-family-tokens
Oct 2, 2026
Merged

onlyarnav merged 1 commit into
apache:mainfrom
liwenjie200543:perf/pairing-family-tokens

Conversation

@liwenjie200543

Copy link
Copy Markdown
Contributor

Summary

  • Applies the Optimize skill token cost across all families (setup-family recipe) #1342 setup-family optimization recipe to the pairing skill family (Optimize the pairing skill family #1352). Both pairing skills were over the 200-token always-on budget — description + when_to_use are paid in every session, for every skill, invoked or not.
  • pairing-multi-agent-review: always-on ~230 → ~172 tokens (chars÷4 estimate); measured body tokens 3,686 → 3,467.
  • pairing-self-review: always-on ~209 → ~170; measured body 3,437 → 3,377.
  • The body pass dedupes prose that repeated the frontmatter description, the per-pass scopes, and golden-rule bodies. Headings, golden-rule headlines, code blocks, and the pre-flight block are byte-identical; all quoted trigger phrases in when_to_use are preserved.

Test plan

  • uv run --project tools/skill-token-count skill-token-count — stamps current, exit 0 (restamped via --write in the same PR).
  • uv run --project tools/skill-and-tool-validator --group dev skill-and-tool-validate — exit 0. The only warnings (override-contract, no-telemetry-import) are pre-existing on files this PR does not touch.
  • python tools/dev/skill-surface-hash.py — reports "surface_hash in sync across 78 skills", i.e. all structural anchors are unchanged.
  • Eval-coupled strings verified present (e.g. the Pass A injection-guard finding text).
  • The behavior eval suites for both skills (15 + 20 cases) require claude -p and were not run in my environment — noted here per the Optimize skill token cost across all families (setup-family recipe) #1342 recipe's "run evals before and after" step. Happy to run them locally on request, or maintainer run appreciated before merge.

Gen-AI disclosure

Prepared with AI coding assistance (ZCode); changes reviewed, tested, and committed by me.

Why: both pairing skills were over the 200-token always-on budget
(apache#1352, umbrella apache#1342) — description and when_to_use are paid in
every session for every skill. Body prose repeated the frontmatter
description, the per-pass scopes, and golden-rule bodies; dedupe it
keeping headings, golden-rule headlines, code blocks, and the
pre-flight block byte-identical.

Always-on (chars/4 estimate): pairing-multi-agent-review ~230 -> 172,
pairing-self-review ~209 -> 170. Measured body tokens (pre-flight
excluded): 3,686 -> 3,467 and 3,437 -> 3,377. surface_hash unchanged;
skill-and-tool-validate green.

Generated-by: ZCode (GLM-5.3-Flash)

@Kaap10 Kaap10 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @liwenjie200543!

Trimming frontmatter on skills is always tricky because it's easy to accidentally drop subtle trigger phrases or prompt context, but this is done really cleanly.

Checked the changes across both multi-agent-review and self-review:

  • Both frontmatters are comfortably under the 200-token budget now without losing any of the when_to_use trigger keywords.
  • The prose deduping in the body keeps the 3-axis isolation model, Step 1–4 pipeline, and Golden Rules completely intact.
  • Measured token counts match.

@onlyarnav onlyarnav left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@onlyarnav
onlyarnav merged commit 8f63162 into apache:main Oct 2, 2026
10 checks passed
@potiuk potiuk added capability:review Deep per-item code review or contributor mentoring family:pairing pairing skills labels Oct 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

capability:review Deep per-item code review or contributor mentoring family:pairing pairing skills

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants