You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
skill metadata: trigger phrases crammed into description; when_to_use is unused and the shared listing budget silently drops them #1271
187SKILL.md files; 135 are model-invocable and therefore occupy the
skill listing.
Those 135 carry 80,026 characters of description into a shared
listing budget.
when_to_use — the dedicated field for trigger phrases, appended to description in the listing — is used in 2 files
(playbooks/boris, playwright/playwright). Everywhere else triggers are
crammed into description as Use when: '…', '…'.
The failure mode is silent. Descriptions are dropped from least-invoked skills
first on overflow, so a skill can lose exactly the trigger words that would have
surfaced it — and nothing reports that it happened. This was found while
investigating why an existing capability appeared not to exist.
Descriptions also open by restating the skill's own name
("Re-anchor research and…" on do-your-research), spending characters against
the cap on a token already on the line.
displayName is out of scope: all 5 uses are acronym casing in marketplace.json, and a semantic rename would be a divergent second use of the
field owing its own recorded rationale.
Direction (no open decision)
Migrate trigger phrases from description into when_to_use across the skills
that lack it, and drop name-restating description prefixes. Both fields feed the
same 1,536-character cap, so this is a structural split rather than a saving by
itself — the saving comes from the prefixes and from not duplicating the name.
Re-measure at authoring time and report the before/after total so the change is
verifiable rather than asserted. The figures above are a point-in-time
measurement, not a contract.
Blocked by
Cleared. PR #1276 merged the re-anchor → discipline rename, so this
migration no longer races a bulk rename of the same files.
Collision risk
No existing issue covers this — searched all states for when_to_use, description, listing, metadata, displayName, trigger, budget.
Closest matches are #304 (fresh-eyes program, unrelated scope) and #1212 (SDLC
stage-gate, matched on the word "metadata" only). If another session is already
carrying this work, this issue is what makes the overlap visible before either
side writes code.
Acceptance
Trigger phrases live in when_to_use; description states what the skill
does
No description opens by restating the skill's own name
displayName is unchanged
Total model-invocable description characters reported before and after
Every touched plugin carries a version bump and CHANGELOG entry
This was generated by AI during a /planning:interview session on the fact-check capability.
The when_to_use migration should not proceed as written. when_to_use is appended to description and shares the same 1,536-character cap
(skills reference), so moving trigger
phrases there relocates them to the truncation tail — where they are cut first.
It makes the failure mode worse, not better.
The root cause is length, not field placement. Official guidance
(skill authoring best practices)
caps description at 1,024 characters and its effective examples run 150–200:
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
Measured on this tree (point-in-time, same caveat as the issue body):
Total description text: 104,752 characters (~26,188 est. tokens) against
a live 9.9k listing cap.
At ~200 characters each, 181 skills ≈ 9,050 est. tokens — under the existing
cap with headroom. Do not raise skillListingBudgetFraction: that carries
the bloat permanently in every session instead of removing it.
Live confirmation the harm is real, not projected (/context all, Opus 5
1M): the Skills row reports 9.9k tokens (1.0%) across 156 entries, and
per-skill rows at < 20 tokens are name-only — description dropped. Five of the
sixteen discipline skills are in that state right now:
Skill
Description on disk
In context
reuse-or-replace
1,022 chars
dropped
do-your-research-deep
796 chars
dropped
use-your-skills
670 chars
dropped
recheck-against-upstream-deep
607 chars
dropped
scrutinize-dont-coast
529 chars
dropped
These cannot be auto-invoked on their trigger words at all; they are reachable
only by explicit / invocation.
Revised acceptance:
No description exceeds 1,024 characters (spec maximum).
Total listing demand measured under the live cap, reported before/after.
/context all shows zero skills at < 20 tokens.
Trigger keywords preserved vs HEAD per skill-quality:check.
skillListingBudgetFraction left unset — the fix is shorter text, not a
bigger budget.
Still out of scope:displayName (unchanged from the issue body — verified
empirically this session: claude plugin list and claude plugin details both
render name, not displayName, against eol-normalizer which sets displayName: "EOL Normalizer").
Blocker status unchanged: the re-anchor → discipline rename is staged
and validating green but not yet merged.
Measured against the shipped binary — the diagnosis holds, the framing should not be "budget saving"
Evidence PR: #1286. It commits the full measurement (algorithm recovered from the Claude Code v2.1.219 binary rather than inferred, plus per-plugin tables, a must-not-flag list, and a re-verification record). Everything below is the short form — the PR is the source of truth, and this comment deliberately does not restate it.
Reconciling the numbers
Three different figures are in play and they are consistent once the population is scoped. All re-derived by script against 39880e3bb7.
Figure
Population
Reproduced
This issue: 80,026 / 135
description only, model-invocable only, repo tree
79,653 / 130 — both figures re-derived by script
Effort handoff: 111,784 / 195
name+description, all invocability, installed+enabled plugins across all marketplaces
192 entries — count re-verified term by term. The 111,578-character total is carried from the measurement and not independently reproduced: it depends on resolving which cached plugin version the harness loads and how it dedupes across marketplaces
File count.find plugins -name SKILL.md returns 188, but 7 sit inside a skill directory — six vendor/ materializations plus one references/ fixture. Discovery is plugins/<plugin>/skills/<name>/SKILL.md, so those are not skills. 181 skills: 130 model-invocable, 51 disable-model-invocation. This issue's 135 / 80,026 is 5 skills and 373 characters above today's tree — ordinary drift, and the issue already calls its figures point-in-time.
Enabled-plugin arithmetic, each term re-counted: 181 − 1 (miro is false in enabledPlugins) + 7 (caveman) + 3 (codex) + 1 (claude-security) + 0 (security-guidance ships no skills/) + 1 (a personal user skill) = 192. The residual to 195 is 3 entries / 206 chars / 0.2%, from builtin commands and an inline-marketplace plugin with no cache entry.
The when_to_use migration is close to character-neutral — this issue is right
The binary joins the two fields with a literal " - ". Moving a trigger block from description into when_to_use therefore costs +3 characters per skill. It is not a saving, and the issue already says so; the implementation confirms it exactly.
The named reduction sources are also smaller than they look: name-restating openers plus pure exclusion clauses total 2.4% of description mass, and only 1.0% is genuinely available once the clauses carrying routing or output contracts are set aside. Of the 236 name-restating characters fleet-wide, 120 are re-anchor's twelve "Re-anchor " prefixes — one plugin's house style, not a fleet-wide tax.
A careful keyword-preserving rewrite of the worst plugin (re-anchor, 12.0% of the listing) recovers −920 chars, −9.2% — and one skill, follow-our-standards, goes up by 13 characters. Treat 9.2% as an upper bound; re-anchor is the most compressible plugin in the tree.
So the honest frame is authoring discipline and future-proofing, not a budget fix. The acceptance criteria are still worth shipping on those grounds.
Why no metadata edit closes the gap
The budget is characters, computed as contextTokens × 4 × 0.01: 40,000 at 1M context, 8,000 at 200k. The 130 model-invocable skills cost 83,270 characters of listing entries (83,399 with inter-entry separators) — roughly 2× over at 1M and 10× over at 200k. Overflow is all-or-nothing per skill: an entry keeps its full text or collapses to - name. There is no partial truncation.
In the observation session, 95 of 130 (73%) model-invocable skills were name-only, with 59,824 characters of description withheld. Whole plugins were dark — all 9 songwriting, all 6 docs-hygiene, all 4 testing, both github.
Caveat, load-bearing: the live listing lives in the system prompt, which no script can read, so that set was transcribed by hand. Any transcription omission inflates the drop count, so 73% is an upper bound and the true figure is at or below it. It is also per-machine usage state (priority is decayed local usage), not a property of the repo — another machine sees a different 35. This has not been upgraded to a measurement.
Zeroing every character the named sources can offer still leaves the listing above 81,000. The drop rate would not move.
The levers that actually move the number — out of scope here
None of these are metadata edits, and this issue should not absorb them:
Fewer listed entries — merging multi-verb siblings, or setting disable-model-invocation on skills that are genuinely user-triggered (DMI skills are excluded from the listing entirely). This is the only lever with real headroom, and it is a design decision this issue does not own.
Raising skillListingBudgetFraction (or SLASH_COMMAND_TOOL_CHAR_BUDGET). Consumer-side settings, not a repo change. Currently unset on the measuring machine, so defaults are in force. Flagged as an open operator decision, deliberately not pulled here.
skillOverrides"name-only" is not available: the docs state it "does not apply to plugin skills", and every skill here is a plugin skill.
The before/after criterion already has a gate — please wire to it, don't build one
Total model-invocable description characters reported before and after
skill-quality:check already enforces the stronger half of this. plugins/skill-quality/scripts/check-skill.sh:236-304 (check 3) extracts single-quoted trigger phrases from descriptionandwhen_to_usecombined, at the base ref and in the working tree, and fails on any phrase lost — with a narrow exception for a phrase deliberately moved to a sibling skill. Moving a phrase between the two fields of the same skill passes; dropping it fails. That is exactly "no discovery was lost", as a gate rather than a claim.
Verified against the prepared re-anchor rewrite using the repo's own extractor (skill-frontmatter.sh:102), not a reimplementation: 122 of 122 trigger phrases preserved, 0 lost.
Three things the incumbent does not do, worth folding into this issue:
Check 2 is a per-skill cap, not a listing-budget cap despite what the skill's description advertises. It guards the 1,536-character per-entry truncation. There is no check on the shared 40,000/8,000 budget at all — which is how it overflowed 10× with nothing reporting it.
Check 2 omits the joiner.check-skill.sh:227 computes DESC_LEN + WTU_LEN, but the entry text is description + " - " + when_to_use. Under-counts by 3 whenever when_to_use is populated. Not currently binding (longest entry in the tree is 1,161 against a 1,536 cap), but wrong in exactly the direction this issue is about.
Check 12 collides with this issue's first acceptance criterion.check-skill.sh:440-448 warns unless the text use when appears in either field. A rewrite that puts bare quoted phrases in when_to_use with no marker warns on every migrated skill — measured: 15 of 15 on the prepared re-anchor block. Two fixes:
Keep a literal Use when: prefix inside when_to_use — no code change, but it costs ~10 characters per skill on top of the joiner's +3. Across 130 model-invocable skills that is roughly +1,700 characters, which would consume most of the 1,906 the named reduction sources can offer and push a fleet-wide migration net-negative on characters. Worth stating plainly, since it makes the "close to character-neutral" framing depend on which fix is chosen.
Amend check 12 to accept a populated, single-quoted when_to_use as satisfying the trigger-spec requirement. This is the better fix — check 12's warning text ("a description is a trigger spec, not a summary") encodes the pre-when_to_use authoring model this issue is deliberately changing — but it edits check-skill.sh, so it sequences behind feat(skill-quality): fresh-eyes delegation doctrine + conformance gate (check 21) #1096.
Still blocked
#1276 (re-anchor → discipline, 45 files) is open and unmerged, so the rewrite is prepared, not applied. The full rewritten frontmatter for all 15 skills is in #1286 §6, ready to apply against the renamed paths. When the rename lands, each listed name gains one character (+15 total) and the sweep-all-disciplines / do-your-research texts that say "re-anchor" need review as trigger phrases.
This was generated by AI during work-loop execution.
Escalated — C4 structural, hard-gated
Carries work-class: structural (C4). Per the admission gate's hard-gate table, C4
structural/contract work is human-gated regardless of any other signal — "Refactors,
migrations, contract changes; cross-cutting and hard to reverse... human review and human
merge are mandatory, always." This item had agent-ready from an earlier triage pass but no needs-human had ever been formally applied, so it kept surfacing on the autonomous frontier
without ever being dispatchable. Applying needs-human now to correct the label state to match
the gate's actual (and unchanged) disposition — this item was never going to be autonomously
worked, this just makes that visible on the tracker instead of silently skipped every cycle.
Re-measured against origin/main before starting, and the measurement changes what this issue should do. Flagging before writing any code.
Current numbers
filed
now
SKILL.md files
187
182
model-invocable
135
131
description chars
80,026
80,296
using when_to_use
2
2
name-restating prefixes
"descriptions also open by restating the name"
4
The premise needs correcting
This issue proposes migrating trigger phrases from description into when_to_use, noting both feed the same 1,536-char cap so the split is structural rather than a saving. That reading of the cap is right, but it is not the binding constraint. Per the skills reference:
The budget scales at 1% of the model's context window. When the listing overflows, Claude Code drops descriptions starting with the skills you invoke least.
each entry's combined text is capped at 1,536 characters regardless of budget
Two independent limits:
Per-entry cap, 1,536 chars. Largest description in the tree is 1,161 (docs-hygiene/skills/audit-derivability). Nothing is near it. Moving text from description to when_to_use cannot help — they are summed for this cap.
Listing budget, 1% of context. 2,000 chars at 200k context, 10,000 at 1M. Against 80,296 measured, the listing is over by 40x at 200k and 8x at 1M.
So the silent-drop failure this issue reports is real and worse than described — but the field split does nothing about it, and the four name-restating prefixes are worth well under 1% of the overflow.
What the doc says actually helps
Three levers, none of which is the when_to_use migration:
skillOverrides: "name-only" — list low-priority skills without a description. Direct budget reduction, and the doc names it first.
skillListingBudgetFraction / SLASH_COMMAND_TOOL_CHAR_BUDGET — raise the budget. A consumer setting, not something this repo ships.
Genuinely shorter descriptions — real reduction, but 80,296 to under 10,000 is an 88% cut across 131 skills, which is a different and much larger project than a field migration.
Also worth noting: /doctor reports the listing's context cost and its biggest contributors, and overflow writes a warning to the debug log under --debug. So the failure is not silent in the way this issue assumes — it is observable, just not somewhere anyone looks.
Proposed re-scope
Keep the finding, replace the fix. This should become a decision about which levers to pull, with the when_to_use migration recorded as considered and rejected — it addresses a cap nothing is hitting.
Marking status: needs-decision and dropping agent-ready: an autonomous session picking this up today would execute a 131-file migration that cannot move the number it targets.
I have not written any code against this. Re-measurement scripts are trivial to re-run if you want the numbers verified independently.
This was generated by AI during a session on the fact-check capability.
Disposition of the evidence PR #1286 — closed, folded here per D-7
D-7 of ADR 0004
folds the listing-budget material into this issue rather than a second ticket. #1286 carried that
material as a contract-tier document under docs/topics/, which docs/conventions/topic-docs/README.md:29-34 makes task-branch-only. A measurement is verification
evidence, not a durable architectural decision, so it does not graduate to an ADR — it folds here and
the PR becomes its citation. #1286 is closed; its diff stays readable and is where the per-plugin
tables, the must-not-flag list, the worked before/after, and the re-verification record live.
The measurement corroborates the re-scope in the comment above, independently
That comment records the when_to_use migration as considered and rejected because it addresses a
cap nothing is hitting. The binary-level measurement reaches the same conclusion by a different route,
which is worth having on the record as convergence rather than repetition:
The harness joins the two fields with a literal " - ", recovered from the shipped v2.1.219
binary rather than inferred. Migrating a trigger block into when_to_use therefore costs +3
characters per skill. It is not a saving in either direction.
The named reduction sources — name-restating openers plus pure exclusion clauses — total 2.4% of
description mass, of which only 1.0% is genuinely available once clauses carrying routing or
output contracts are set aside.
A careful keyword-preserving rewrite of the single most compressible plugin recovers −9.2% of
its own mass, and one skill in it goes up by 13 characters. Treat 9.2% as an upper bound.
Zeroing every recoverable character still leaves the listing well above 81,000. No metadata
edit closes the gap.
The prepared 15-skill rewrite in §6 of that PR is therefore not being revived. It is the rejected
fix, and this comment records it as dead rather than parked, so a later session does not rediscover it
as available work.
One discrepancy to settle before any number is asserted
Two figures for the same budget are now on this issue and they differ by 4×:
Source
1M context
200k context
Derived from the binary: contextTokens × 4 × 0.01 characters
40,000
8,000
Read from the docs' "1% of the model's context window"
10,000
2,000
The difference is whether the 1% applies to tokens (then converted to characters) or to characters
directly. It moves the reported overflow from roughly 2× to roughly 8× at 1M context. Both
readings agree the listing overflows and that the field migration does not help, so the re-scope holds
either way — but a decision that names a target number needs this settled first, against the binary or
against /doctor's reported listing cost.
Also worth carrying forward from the measurement: skillListingBudgetFraction is 0.03 on the
measuring machine, not the documented 0.01 default. Any lever priced against the default is
priced wrong there.
The actionable residue is now its own ticket
The measurement audited the incumbent gate before proposing anything, and found four defects in skill-quality:check — most importantly that there is no check on the shared listing budget at
all, which is how the overflow went unreported. Those are code fixes independent of how this
issue's lever decision lands, so they are filed as #1404 rather than left inside this issue's
scope.
What is unchanged here
This comment routes and records; it does not re-decide. This issue keeps status: needs-decision,
and the lever choice — skillOverrides: "name-only", the consumer budget settings, or a genuinely
shorter-description project — remains the operator's.
The budget discrepancy is settled: it is tokens × 4, not characters
The prior comment left one thing open — whether skillListingBudgetFraction applies to the context
window in tokens (then converted to characters) or to characters directly — and noted that a
decision naming a target number needs it settled first. Settled here against the shipped binary.
The function, verbatim
Recovered from claude.exev2.1.220 (the prior measurement used v2.1.219):
$hy = 200000 is the tell — 200,000 is the context window in tokens, not characters, and it is
multiplied by J5u = 4 before the fraction is applied. The settings schema's own wording agrees: "Fraction of the context window (in characters)" means the context window expressed in
characters, not a fraction taken of a character count.
The binary-derived reading was right. The chars-direct reading (10,000 / 2,000) is wrong — it
treated the context window's token count as a character count and lost a factor of 4.
Corrected numbers
Budget, by fraction and context size:
fraction
200k context
1M context
0.01 (default)
8,000
40,000
0.03 (this machine)
24,000
120,000
Against the 80,296 description chars measured on this issue:
fraction
200k context
1M context
0.01 (default)
10.0× over
2.01× over
0.03 (this machine)
3.35× over
under budget (67% of it)
Three consequences
The "40× overflow" figure is dead. It was 80,296 / 2,000 — the wrong reading and the
200k row. Nothing on this issue should carry it forward. The correct default-fraction figures
are 10.0× at 200k and 2.01× at 1M.
This machine does not overflow at all on a 1M-context model.skillListingBudgetFraction
is 0.03 in ~/.claude/settings.json, giving a 120,000-char budget against ~80k of
descriptions. That is why truncation is not observed locally, and it means the local
environment is not a witness for the overflow — anything measured here is measured with the
symptom suppressed.
The conclusion is unchanged. The overflow is real at the documented default, and the when_to_use migration still does not help — RLt re-confirms on 2.1.220 that the two fields
are joined with a literal " - " and the sum is what the 1,536 per-entry cap sees:
SLASH_COMMAND_TOOL_CHAR_BUDGET short-circuits the entire computation. It is read first and
returned directly, so it overrides both the fraction and the context size. It is not in the
settings schema — it is env-only — and it belongs on the lever list alongside skillOverrides: "name-only" and skillListingBudgetFraction.
80,296 is description mass, so every multiple above is a floor. The rendered listing is - ${name}: ${description} per line plus newline separators, so the real total exceeds the
description sum by roughly name.length + 4 per skill plus one newline each. The true overflow
is slightly worse than stated, never better.
What was tried and did not work
Forcing the over-budget warn path (SLASH_COMMAND_TOOL_CHAR_BUDGET=1, claude --debug -p) to read
the exact rendered listing size produced no listing diagnostics — headless --debug emitted only the
model reply. The formula above is therefore binary-sourced rather than confirmed against a live
warning, and the rendered-listing total remains the one number here not directly measured.
Status
This comment settles a number; it does not decide the lever. The issue keeps status: needs-decision, and the choice among skillOverrides: "name-only", the consumer budget settings,
and a shorter-description project remains the operator's.
The listing-budget arithmetic and when_to_use field behavior are settled in-thread (tokens×4 formula, 80k description mass at default fraction, RLt join semantics). What remains is an operator lever choice among skillOverrides: "name-only", skillListingBudgetFraction, and fleet-wide description trimming — not an open defect. Fleet metadata normalization is tracked on the standing carrier #1617.
Re-open trigger: A concrete acceptance brief naming which lever the fleet adopts and what “done” looks like in SKILL.md files.
Activity
kyle-sexton commentedon Jul 24, 2026
Correction to Direction, from live measurement.
The
when_to_usemigration should not proceed as written.when_to_useisappended to
descriptionand shares the same 1,536-character cap(skills reference), so moving trigger
phrases there relocates them to the truncation tail — where they are cut first.
It makes the failure mode worse, not better.
The root cause is length, not field placement. Official guidance
(skill authoring best practices)
caps
descriptionat 1,024 characters and its effective examples run150–200:
Measured on this tree (point-in-time, same caveat as the issue body):
docs-hygiene:audit-derivability1161,session-flow:running-retro1116,session-flow:reconcile1072,adhd:clarify1058,architecture:improve1057,discipline:script-the-deterministic-work1054,planning:audit-answers1028.descriptiontext: 104,752 characters (~26,188 est. tokens) againsta live 9.9k listing cap.
At ~200 characters each, 181 skills ≈ 9,050 est. tokens — under the existing
cap with headroom. Do not raise
skillListingBudgetFraction: that carriesthe bloat permanently in every session instead of removing it.
Live confirmation the harm is real, not projected (
/context all, Opus 51M): the Skills row reports 9.9k tokens (1.0%) across 156 entries, and
per-skill rows at
< 20 tokensare name-only — description dropped. Five of thesixteen
disciplineskills are in that state right now:reuse-or-replacedo-your-research-deepuse-your-skillsrecheck-against-upstream-deepscrutinize-dont-coastThese cannot be auto-invoked on their trigger words at all; they are reachable
only by explicit
/invocation.Revised acceptance:
descriptionexceeds 1,024 characters (spec maximum)./context allshows zero skills at< 20 tokens.skill-quality:check.skillListingBudgetFractionleft unset — the fix is shorter text, not abigger budget.
Still out of scope:
displayName(unchanged from the issue body — verifiedempirically this session:
claude plugin listandclaude plugin detailsbothrender
name, notdisplayName, againsteol-normalizerwhich setsdisplayName: "EOL Normalizer").Blocker status unchanged: the
re-anchor→disciplinerename is stagedand validating green but not yet merged.
refactor(discipline): rename re-anchor plugin to discipline (#1276)
kyle-sexton commentedon Jul 25, 2026
placeholder
kyle-sexton commentedon Jul 25, 2026
Measured against the shipped binary — the diagnosis holds, the framing should not be "budget saving"
Evidence PR: #1286. It commits the full measurement (algorithm recovered from the Claude Code v2.1.219 binary rather than inferred, plus per-plugin tables, a must-not-flag list, and a re-verification record). Everything below is the short form — the PR is the source of truth, and this comment deliberately does not restate it.
Reconciling the numbers
Three different figures are in play and they are consistent once the population is scoped. All re-derived by script against
39880e3bb7.descriptiononly, model-invocable only, repo treename+description, all invocability, installed+enabled plugins across all marketplacesFile count.
find plugins -name SKILL.mdreturns 188, but 7 sit inside a skill directory — sixvendor/materializations plus onereferences/fixture. Discovery isplugins/<plugin>/skills/<name>/SKILL.md, so those are not skills. 181 skills: 130 model-invocable, 51disable-model-invocation. This issue's 135 / 80,026 is 5 skills and 373 characters above today's tree — ordinary drift, and the issue already calls its figures point-in-time.Enabled-plugin arithmetic, each term re-counted: 181 − 1 (
miroisfalseinenabledPlugins) + 7 (caveman) + 3 (codex) + 1 (claude-security) + 0 (security-guidanceships noskills/) + 1 (a personal user skill) = 192. The residual to 195 is 3 entries / 206 chars / 0.2%, from builtin commands and an inline-marketplace plugin with no cache entry.The
when_to_usemigration is close to character-neutral — this issue is rightThe binary joins the two fields with a literal
" - ". Moving a trigger block fromdescriptionintowhen_to_usetherefore costs +3 characters per skill. It is not a saving, and the issue already says so; the implementation confirms it exactly.The named reduction sources are also smaller than they look: name-restating openers plus pure exclusion clauses total 2.4% of description mass, and only 1.0% is genuinely available once the clauses carrying routing or output contracts are set aside. Of the 236 name-restating characters fleet-wide, 120 are
re-anchor's twelve"Re-anchor "prefixes — one plugin's house style, not a fleet-wide tax.A careful keyword-preserving rewrite of the worst plugin (
re-anchor, 12.0% of the listing) recovers −920 chars, −9.2% — and one skill,follow-our-standards, goes up by 13 characters. Treat 9.2% as an upper bound;re-anchoris the most compressible plugin in the tree.So the honest frame is authoring discipline and future-proofing, not a budget fix. The acceptance criteria are still worth shipping on those grounds.
Why no metadata edit closes the gap
The budget is characters, computed as
contextTokens × 4 × 0.01: 40,000 at 1M context, 8,000 at 200k. The 130 model-invocable skills cost 83,270 characters of listing entries (83,399 with inter-entry separators) — roughly 2× over at 1M and 10× over at 200k. Overflow is all-or-nothing per skill: an entry keeps its full text or collapses to- name. There is no partial truncation.In the observation session, 95 of 130 (73%) model-invocable skills were name-only, with 59,824 characters of description withheld. Whole plugins were dark — all 9
songwriting, all 6docs-hygiene, all 4testing, bothgithub.Zeroing every character the named sources can offer still leaves the listing above 81,000. The drop rate would not move.
The levers that actually move the number — out of scope here
None of these are metadata edits, and this issue should not absorb them:
disable-model-invocationon skills that are genuinely user-triggered (DMI skills are excluded from the listing entirely). This is the only lever with real headroom, and it is a design decision this issue does not own.skillListingBudgetFraction(orSLASH_COMMAND_TOOL_CHAR_BUDGET). Consumer-side settings, not a repo change. Currently unset on the measuring machine, so defaults are in force. Flagged as an open operator decision, deliberately not pulled here.skillOverrides"name-only"is not available: the docs state it "does not apply to plugin skills", and every skill here is a plugin skill.The before/after criterion already has a gate — please wire to it, don't build one
skill-quality:checkalready enforces the stronger half of this.plugins/skill-quality/scripts/check-skill.sh:236-304(check 3) extracts single-quoted trigger phrases fromdescriptionandwhen_to_usecombined, at the base ref and in the working tree, and fails on any phrase lost — with a narrow exception for a phrase deliberately moved to a sibling skill. Moving a phrase between the two fields of the same skill passes; dropping it fails. That is exactly "no discovery was lost", as a gate rather than a claim.Verified against the prepared
re-anchorrewrite using the repo's own extractor (skill-frontmatter.sh:102), not a reimplementation: 122 of 122 trigger phrases preserved, 0 lost.Three things the incumbent does not do, worth folding into this issue:
Check 2 is a per-skill cap, not a listing-budget cap despite what the skill's description advertises. It guards the 1,536-character per-entry truncation. There is no check on the shared 40,000/8,000 budget at all — which is how it overflowed 10× with nothing reporting it.
Check 2 omits the joiner.
check-skill.sh:227computesDESC_LEN + WTU_LEN, but the entry text isdescription + " - " + when_to_use. Under-counts by 3 wheneverwhen_to_useis populated. Not currently binding (longest entry in the tree is 1,161 against a 1,536 cap), but wrong in exactly the direction this issue is about.Check 12 collides with this issue's first acceptance criterion.
check-skill.sh:440-448warns unless the textuse whenappears in either field. A rewrite that puts bare quoted phrases inwhen_to_usewith no marker warns on every migrated skill — measured: 15 of 15 on the preparedre-anchorblock. Two fixes:Keep a literal
Use when:prefix insidewhen_to_use— no code change, but it costs ~10 characters per skill on top of the joiner's +3. Across 130 model-invocable skills that is roughly +1,700 characters, which would consume most of the 1,906 the named reduction sources can offer and push a fleet-wide migration net-negative on characters. Worth stating plainly, since it makes the "close to character-neutral" framing depend on which fix is chosen.Amend check 12 to accept a populated, single-quoted
when_to_useas satisfying the trigger-spec requirement. This is the better fix — check 12's warning text ("a description is a trigger spec, not a summary") encodes the pre-when_to_useauthoring model this issue is deliberately changing — but it editscheck-skill.sh, so it sequences behind feat(skill-quality): fresh-eyes delegation doctrine + conformance gate (check 21) #1096.Still blocked
#1276 (
re-anchor→discipline, 45 files) is open and unmerged, so the rewrite is prepared, not applied. The full rewritten frontmatter for all 15 skills is in #1286 §6, ready to apply against the renamed paths. When the rename lands, each listed name gains one character (+15 total) and thesweep-all-disciplines/do-your-researchtexts that say "re-anchor" need review as trigger phrases.docs(topics): quantify the check-12 workaround's character cost
fix(plugin-quality): state the deep-phase requirement as an invariant…
kyle-sexton commentedon Jul 25, 2026
This was generated by AI during work-loop execution.
Escalated — C4 structural, hard-gated
Carries
work-class: structural(C4). Per the admission gate's hard-gate table, C4structural/contract work is human-gated regardless of any other signal — "Refactors,
migrations, contract changes; cross-cutting and hard to reverse... human review and human
merge are mandatory, always." This item had
agent-readyfrom an earlier triage pass but noneeds-humanhad ever been formally applied, so it kept surfacing on the autonomous frontierwithout ever being dispatchable. Applying
needs-humannow to correct the label state to matchthe gate's actual (and unchanged) disposition — this item was never going to be autonomously
worked, this just makes that visible on the tracker instead of silently skipped every cycle.
kyle-sexton commentedon Jul 25, 2026
Re-measured against
origin/mainbefore starting, and the measurement changes what this issue should do. Flagging before writing any code.Current numbers
SKILL.mdfileswhen_to_useThe premise needs correcting
This issue proposes migrating trigger phrases from
descriptionintowhen_to_use, noting both feed the same 1,536-char cap so the split is structural rather than a saving. That reading of the cap is right, but it is not the binding constraint. Per the skills reference:Two independent limits:
docs-hygiene/skills/audit-derivability). Nothing is near it. Moving text fromdescriptiontowhen_to_usecannot help — they are summed for this cap.So the silent-drop failure this issue reports is real and worse than described — but the field split does nothing about it, and the four name-restating prefixes are worth well under 1% of the overflow.
What the doc says actually helps
Three levers, none of which is the
when_to_usemigration:skillOverrides: "name-only"— list low-priority skills without a description. Direct budget reduction, and the doc names it first.skillListingBudgetFraction/SLASH_COMMAND_TOOL_CHAR_BUDGET— raise the budget. A consumer setting, not something this repo ships.Also worth noting:
/doctorreports the listing's context cost and its biggest contributors, and overflow writes a warning to the debug log under--debug. So the failure is not silent in the way this issue assumes — it is observable, just not somewhere anyone looks.Proposed re-scope
Keep the finding, replace the fix. This should become a decision about which levers to pull, with the
when_to_usemigration recorded as considered and rejected — it addresses a cap nothing is hitting.Marking
status: needs-decisionand droppingagent-ready: an autonomous session picking this up today would execute a 131-file migration that cannot move the number it targets.I have not written any code against this. Re-measurement scripts are trivial to re-run if you want the numbers verified independently.
This was generated by AI during a session on the fact-check capability.
kyle-sexton commentedon Jul 25, 2026
Disposition of the evidence PR #1286 — closed, folded here per D-7
D-7 of ADR 0004
folds the listing-budget material into this issue rather than a second ticket. #1286 carried that
material as a contract-tier document under
docs/topics/, whichdocs/conventions/topic-docs/README.md:29-34makes task-branch-only. A measurement is verificationevidence, not a durable architectural decision, so it does not graduate to an ADR — it folds here and
the PR becomes its citation. #1286 is closed; its diff stays readable and is where the per-plugin
tables, the must-not-flag list, the worked before/after, and the re-verification record live.
The measurement corroborates the re-scope in the comment above, independently
That comment records the
when_to_usemigration as considered and rejected because it addresses acap nothing is hitting. The binary-level measurement reaches the same conclusion by a different route,
which is worth having on the record as convergence rather than repetition:
" - ", recovered from the shipped v2.1.219binary rather than inferred. Migrating a trigger block into
when_to_usetherefore costs +3characters per skill. It is not a saving in either direction.
description mass, of which only 1.0% is genuinely available once clauses carrying routing or
output contracts are set aside.
its own mass, and one skill in it goes up by 13 characters. Treat 9.2% as an upper bound.
edit closes the gap.
The prepared 15-skill rewrite in §6 of that PR is therefore not being revived. It is the rejected
fix, and this comment records it as dead rather than parked, so a later session does not rediscover it
as available work.
One discrepancy to settle before any number is asserted
Two figures for the same budget are now on this issue and they differ by 4×:
contextTokens × 4 × 0.01charactersThe difference is whether the 1% applies to tokens (then converted to characters) or to characters
directly. It moves the reported overflow from roughly 2× to roughly 8× at 1M context. Both
readings agree the listing overflows and that the field migration does not help, so the re-scope holds
either way — but a decision that names a target number needs this settled first, against the binary or
against
/doctor's reported listing cost.Also worth carrying forward from the measurement:
skillListingBudgetFractionis0.03on themeasuring machine, not the documented
0.01default. Any lever priced against the default ispriced wrong there.
The actionable residue is now its own ticket
The measurement audited the incumbent gate before proposing anything, and found four defects in
skill-quality:check— most importantly that there is no check on the shared listing budget atall, which is how the overflow went unreported. Those are code fixes independent of how this
issue's lever decision lands, so they are filed as #1404 rather than left inside this issue's
scope.
What is unchanged here
This comment routes and records; it does not re-decide. This issue keeps
status: needs-decision,and the lever choice —
skillOverrides: "name-only", the consumer budget settings, or a genuinelyshorter-description project — remains the operator's.
docs(adr): make every lane's outcome resolvable from a clone
kyle-sexton commentedon Jul 25, 2026
The budget discrepancy is settled: it is tokens × 4, not characters
The prior comment left one thing open — whether
skillListingBudgetFractionapplies to the contextwindow in tokens (then converted to characters) or to characters directly — and noted that a
decision naming a target number needs it settled first. Settled here against the shipped binary.
The function, verbatim
Recovered from
claude.exev2.1.220 (the prior measurement used v2.1.219):All four constants resolve in the same bundle:
J5u4Nhy0.01skillListingBudgetFraction$hy200000Fhy1536skillListingMaxDescCharsSo the budget is:
$hy = 200000is the tell — 200,000 is the context window in tokens, not characters, and it ismultiplied by
J5u = 4before the fraction is applied. The settings schema's own wording agrees:"Fraction of the context window (in characters)" means the context window expressed in
characters, not a fraction taken of a character count.
The binary-derived reading was right. The chars-direct reading (10,000 / 2,000) is wrong — it
treated the context window's token count as a character count and lost a factor of 4.
Corrected numbers
Budget, by fraction and context size:
0.01(default)0.03(this machine)Against the 80,296 description chars measured on this issue:
0.01(default)0.03(this machine)Three consequences
The "40× overflow" figure is dead. It was
80,296 / 2,000— the wrong reading and the200k row. Nothing on this issue should carry it forward. The correct default-fraction figures
are 10.0× at 200k and 2.01× at 1M.
This machine does not overflow at all on a 1M-context model.
skillListingBudgetFractionis
0.03in~/.claude/settings.json, giving a 120,000-char budget against ~80k ofdescriptions. That is why truncation is not observed locally, and it means the local
environment is not a witness for the overflow — anything measured here is measured with the
symptom suppressed.
The conclusion is unchanged. The overflow is real at the documented default, and the
when_to_usemigration still does not help —RLtre-confirms on 2.1.220 that the two fieldsare joined with a literal
" - "and the sum is what the 1,536 per-entry cap sees:Two things worth carrying forward
SLASH_COMMAND_TOOL_CHAR_BUDGETshort-circuits the entire computation. It is read first andreturned directly, so it overrides both the fraction and the context size. It is not in the
settings schema — it is env-only — and it belongs on the lever list alongside
skillOverrides: "name-only"andskillListingBudgetFraction.- ${name}: ${description}per line plus newline separators, so the real total exceeds thedescription sum by roughly
name.length + 4per skill plus one newline each. The true overflowis slightly worse than stated, never better.
What was tried and did not work
Forcing the over-budget warn path (
SLASH_COMMAND_TOOL_CHAR_BUDGET=1,claude --debug -p) to readthe exact rendered listing size produced no listing diagnostics — headless
--debugemitted only themodel reply. The formula above is therefore binary-sourced rather than confirmed against a live
warning, and the rendered-listing total remains the one number here not directly measured.
Status
This comment settles a number; it does not decide the lever. The issue keeps
status: needs-decision, and the choice amongskillOverrides: "name-only", the consumer budget settings,and a shorter-description project remains the operator's.
feat(skill-quality): add the shared listing-budget report, fix check …
feat(claude-config): make audit Category G executable and give the sk…
kyle-sexton commentedon Aug 13, 2026
Frontier disposition (drain session)
Ruling: Close as not planned for this drain wave.
The listing-budget arithmetic and
when_to_usefield behavior are settled in-thread (tokens×4 formula, 80k description mass at default fraction,RLtjoin semantics). What remains is an operator lever choice amongskillOverrides: "name-only",skillListingBudgetFraction, and fleet-wide description trimming — not an open defect. Fleet metadata normalization is tracked on the standing carrier #1617.Re-open trigger: A concrete acceptance brief naming which lever the fleet adopts and what “done” looks like in
SKILL.mdfiles.