skill metadata: trigger phrases crammed into description; when_to_use is unused and the shared listing budget silently drops them

[kyle-sexton]

Observation

Measured on the tree as of filing:

• 187 SKILL.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: '…', '…'.
• discipline (renamed from re-anchor by refactor(discipline): rename re-anchor plugin to discipline #1276) alone is 14 skills and 8,809 characters, roughly 11% of the
  budget from one plugin.

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.

[kyle-sexton]

Correction to Direction, from live measurement.

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):

• 7 descriptions exceed the 1,024-character spec maximum:
  docs-hygiene:audit-derivability 1161, session-flow:running-retro 1116,
  session-flow:reconcile 1072, adhd:clarify 1058,
  architecture:improve 1057, discipline:script-the-deterministic-work 1054,
  planning:audit-answers 1028.
• 173 of 181 exceed ~250 characters; 1 is within.
• 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.

[kyle-sexton]

placeholder

[kyle-sexton]

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:

1. 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.
2. 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.
3. 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 description and when_to_use combined, 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.

[kyle-sexton]

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.

[kyle-sexton]

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:

1. skillOverrides: "name-only" — list low-priority skills without a description. Direct budget reduction, and the doc names it first.
2. skillListingBudgetFraction / SLASH_COMMAND_TOOL_CHAR_BUDGET — raise the budget. A consumer setting, not something this repo ships.
3. 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.