Context
Only skill/command/agent description: frontmatter is preloaded into the
system prompt — it is paid on every turn of every session, whether or
not the item is ever used. Measured always-on cost today: ~3,840 tok
(github-workflow) + ~2,820 tok (local-workflow) = ~6,660 tok/turn when
both are installed.
The dominant driver is exhaustive Trigger: "...", "...", ... synonym
lists (e.g. setup ~16 phrases, pick-story ~11, report-issue ~11).
Claude already does semantic matching on the prose, so the synonym dumps
are largely redundant tokens. Two skill descriptions also exceed
Anthropic's hard 1,024-char limit and risk truncation:
code-review (~1,157) and execute (~934).
See docs/context-optimization-plan.md → Lever A and Lever C.
Requirements (acceptance criteria)
Savings goal
~2,500 tok/turn reclaimed on always-on metadata when both plugins are
installed (~1,300 with one). Plus correctness: zero descriptions over
1,024 chars. Re-measure with count-tokens.sh and record the new baseline.
Context
Only skill/command/agent
description:frontmatter is preloaded into thesystem prompt — it is paid on every turn of every session, whether or
not the item is ever used. Measured always-on cost today: ~3,840 tok
(github-workflow) + ~2,820 tok (local-workflow) = ~6,660 tok/turn when
both are installed.
The dominant driver is exhaustive
Trigger: "...", "...", ...synonymlists (e.g.
setup~16 phrases,pick-story~11,report-issue~11).Claude already does semantic matching on the prose, so the synonym dumps
are largely redundant tokens. Two skill descriptions also exceed
Anthropic's hard 1,024-char limit and risk truncation:
code-review(~1,157) andexecute(~934).See
docs/context-optimization-plan.md→ Lever A and Lever C.Requirements (acceptance criteria)
distinct-intent triggers and drop pure synonyms ("ship it"/"done"/"wrap
up"/"submit" → keep one). Keep the "what it does + when to use" prose and
the "Do NOT use for X (use Y)" disambiguation intact (trim, don't delete).
code-reviewandexecutedescriptions are brought under 1,024chars with margin (target ≤ ~900).
_shared-skills/source where a skillis shared;
./sync-skills.ps1/.shis run; canonical + synced copies arecommitted together (repo rule 1+2).
bash sync-skills.sh --verify && bash lint-skills.sh && bash run-tests.sh. The offline decision-logic(trigger/selection) tests stay green.
still has at least one trigger for every distinct user intent it covered.
Savings goal
~2,500 tok/turn reclaimed on always-on metadata when both plugins are
installed (~1,300 with one). Plus correctness: zero descriptions over
1,024 chars. Re-measure with
count-tokens.shand record the new baseline.