perf(skills): skill listing is 42% over its character budget; ~50 skills lose their descriptions and become undiscoverable

[kyle-sexton]

Warning

The figures and the arithmetic below are superseded. Corrected values are in this issue's comments and restated here. Do not work from the original body.

Corrected measurement

My original count globbed find -name SKILL.md recursively. Claude Code discovers skills at skills/<name>/SKILL.md — direct children only — so seven nested files were wrongly included (two playbooks vendor baselines, one playwright, two context7, two docs-hygiene eval fixtures).

	Originally stated	Correct
Listing-eligible skills	170	163
Combined description + when_to_use	127,944 chars	120,723 chars
Overflow vs the 90,000-char budget (fraction: 0.03)	+37,944 (42%)	+30,723 (34%)
Mean / median	752 / 710	740 / 730
Max single entry	5,484	1,528
Entries over the 1,536 listing cap	1	0
Entries over the 1,024 spec max	21	20

Withdrawn: the claim that any skill exceeds the 1,536-char listing cap. None do. The 5,484-char outlier was the boris vendor baseline, which is never loaded — see #3506, closed as invalid.

Arithmetic error, corrected: the original body said "170 x 200 = 34,000 chars. That fits inside the default 30,000-char budget." It does not. At the stock fraction: 0.01 the budget is 30,000 chars, so fitting 163 skills there needs a mean of ~184 chars — which is, coincidentally, almost exactly Anthropic's own worked-example length (~176). At 0.03 (90,000) the mean may be up to ~552; at 0.05 (150,000), ~920.

What is actually true and still worth doing

• Mean description is 740 chars against Anthropic's worked examples at ~176.
• The fleet is 34% over budget at fraction: 0.03, and Claude Code responds by dropping whole descriptions from the least-invoked skills — roughly 50 skills list as bare names and cannot be keyword-matched.
• At fraction: 0.05 the fleet fits with 29,277 chars of headroom, so a consumer on 0.05 has no active truncation today. This is therefore a headroom-and-growth problem, not an active-truncation one, for those consumers.

Do not re-derive the per-field half

skill-quality's check already enforces check 2b (DESC_FIELD_CAP=1024, the Agent Skills spec field maximum) as a WARN, added in 0.19.0 via #3119, and the ~19 breaching skills are already known. The "20 entries over 1024" slice is already visible to the repo's own tooling.

What no per-skill check can catch is the aggregate — every one of the 163 is individually under the 1,536 gate and 143 are under 1,024 too. The overflow exists only in the sum, which is exactly why check-listing-budget.sh is advisory and exits 0. That aggregate is what this issue tracks.

Consumer-side lever: measured, and rejected

skillListingMaxDescChars: 400 was trialled and reverted. At fraction: 0.05 no cap is needed, and a 400 cap is actively harmful: of the 163 eligible skills, 160 carry a Use when: trigger block, and in 45 of them it starts past character 400 — so the cap strips routing keywords from 28% of the fleet. Trimming at source, with the key use case first, is the only lever that does not trade one discoverability failure for another.

Verification criterion

Prefer the repo's own tool over a hand count: skill-quality:check listing-budget reports under budget.

---

Original body — SUPERSEDED by the block above. Kept for the record; do not work from its numbers or checklists.

Summary

The marketplace's skill descriptions are collectively too long. On a machine with the fleet enabled, the skill listing overflows Claude Code's character budget, and Claude Code responds by stripping descriptions from the least-invoked skills — which makes those skills undiscoverable, which keeps them least-invoked. It is self-reinforcing.

This is measured, not inferred.

Evidence

Claude Code's own debug log on an affected machine:

[WARN] Skill listing over budget: 194 skills, 127555 chars > 90000 budget
       — descriptions will be truncated. Run /skills to disable some, or raise skillListingBudgetFraction

Current measurement across the enabled fleet (listing-eligible = excludes disable-model-invocation: true):

Metric	Value
Listing-eligible skills	170
Combined description + when_to_use	127,944 chars
Budget (at skillListingBudgetFraction: 0.03)	90,000 chars
Overflow	+37,944 chars (42% over)
Mean per skill	752 chars
Median	710 chars
Max	5,484 chars
Skills over 500 chars	135 of 170

Note the budget above is already 3× the default. At the stock 0.01 the budget is 30,000 chars and the fleet is 4.3× over.

when_to_use is not the problem — it totals 215 chars fleet-wide. This is entirely description length.

Why this is the wrong length

Per Skill authoring best practices, the description should state "what the Skill does and when to use it." Anthropic's own worked examples run ~150-200 characters:

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.

That is 176 chars. Our fleet mean is 752 — roughly 4× Anthropic's demonstrated style.

The same page states the operative principle directly: "The context window is a public good. Your Skill shares the context window with everything else Claude needs to know, including ... Other Skills' metadata."

Mechanism (why truncation is worse than it sounds)

Per Extend Claude with skills — "Skill descriptions are cut short":

The listing always contains every skill name, but if you have many skills, Claude Code shortens descriptions to fit the listing's character budget, which can strip the keywords Claude needs to match your request. 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, so the skills you use most keep their full text.

Observed live in a session with this fleet: roughly 50 skills currently appear as bare names with no description, including testing:* (all 5), work-items:* (all 9), planning:* (7 of 11), review:code-review, review:fanout, review:security-review, toolchain:*, verification:*, and prototype:*. Claude cannot auto-match any of them — they are effectively manual-invocation-only despite not being configured that way.

Worst offenders by plugin (combined listing chars)

   9568   15 skills  mean= 637  discipline
   9266   13 skills  mean= 712  session-flow
   8255    9 skills  mean= 917  work-items
   7954    9 skills  mean= 883  claude-ops
   7785    5 skills  mean=1557  playbooks
   7699   11 skills  mean= 699  docs-hygiene
   7698   11 skills  mean= 699  planning
   6803    9 skills  mean= 755  claude-config
   4425    5 skills  mean= 885  code-tidying
   4206    5 skills  mean= 841  knowledge
   3967    5 skills  mean= 793  discovery
   3599    4 skills  mean= 899  instruction-placement
   3364    3 skills  mean=1121  overengineering

Proposed work

Trim description toward Anthropic's demonstrated shape: what it does + when to use it, key use case first, target ~200 chars, hard ceiling 400.

The current descriptions are long mostly because they carry an exhaustive trigger-phrase list and a "Skip when / Not for" disambiguation block. Those are real information, but they belong in the SKILL.md body, not in always-resident metadata. Keep the highest-signal trigger keywords in the description; move the exhaustive lists and boundary sections into the body.

Suggested ordering (highest chars first): discipline, session-flow, work-items, claude-ops, playbooks, docs-hygiene, planning, claude-config.

Arithmetic: 170 skills × 200 chars = 34,000 chars. That fits inside the default 30,000-char budget at ~200 chars... to be strictly under stock default, target ~176 chars/skill. At a 400-char ceiling the fleet lands at 68,000 chars — comfortably inside the current 90,000 budget with room for growth.

Acceptance criteria

• No listing-eligible skill has a combined description + when_to_use over 400 chars.
• Fleet total combined listing text is under 68,000 chars.
• Every skill's trigger keywords are preserved somewhere — description or body — with no loss of the terms that drive matching (this repo's skill-quality:check has a trigger-keyword-preservation-vs-HEAD check; it should pass).
• claude --debug on a machine with the fleet enabled no longer logs Skill listing over budget.

Guardrail

Do not achieve the target by deleting trigger keywords — that trades one discoverability failure for another. The win comes from moving prose (rationale, boundary/"skip when" text, exhaustive phrase enumerations) into the body, not from making descriptions vague. Anthropic's guidance explicitly warns against vague descriptions like Helps with documents.

Sources

• https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
• https://code.claude.com/docs/en/skills (section: "Skill descriptions are cut short")
• https://code.claude.com/docs/en/settings-reference (skillListingBudgetFraction, skillListingMaxDescChars, skillOverrides)

[kyle-sexton]

Correction: my measurement over-counted. The problem is real but ~20% smaller, and one claim is withdrawn entirely.

I globbed find -name SKILL.md recursively. Claude Code discovers skills at skills/<name>/SKILL.md — direct children only — so seven nested files were counted that never enter the listing: two playbooks vendor baselines, one playwright, two context7, and two docs-hygiene eval fixtures.

Corrected measurement (direct-child only, enabled fleet, disable-model-invocation excluded):

	Originally reported	Corrected
Listing-eligible skills	170	163
Combined description + when_to_use	127,944 chars	120,723 chars
Overflow vs the 90,000-char budget	+37,944 (42%)	+30,723 (34%)
Mean per skill	752	740
Median	710	730
Max	5,484	1,528
Over the 1,536-char listing cap	1	0
Over the 1,024-char spec max	21	20

Withdrawn: the claim that any skill exceeds Claude Code's 1,536-char listing cap. None do. The 5,484-char outlier was the boris vendor baseline, which is never loaded — see #3506, now closed as invalid.

Unchanged and still the point: mean description is 740 chars against Anthropic's own worked examples at ~176, and the fleet is 34% over budget at skillListingBudgetFraction: 0.03, which is already 3x the stock default. Claude Code responds by dropping descriptions from the least-invoked skills, so roughly 50 skills currently list as bare names and cannot be matched by keyword.

New, and it changes the urgency: at skillListingBudgetFraction: 0.05 the budget is 150,000 chars and the current fleet fits with 29,277 chars of headroom. So a consumer already on 0.05 has no overflow today. That does not retire this issue — it makes it a headroom problem rather than an active-truncation one, and the fleet grows continuously — but it should be weighed when prioritising.

Per-entry cap arithmetic (still 163 skills, so it is the lever that works at any budget):

cap   total    fits 90k   fits 150k
300   48,282   yes        yes
350   56,151   yes        yes
400   63,863   yes        yes
450   71,170   yes        yes
500   78,059   yes        yes

Every cap from 300 up fits both budgets, because capping removes the long tail rather than the median. skillListingMaxDescChars: 400 is a one-line consumer-side mitigation that takes the listing to 63,863 chars while every skill keeps a description; it does not substitute for trimming at source, which is what this issue tracks.

Suggested ordering is unchanged — the plugins with the most listing chars are still the right place to start; only the totals shift slightly. The 20 entries over the 1,024-char Agent Skills spec maximum are the cleanest first slice: they are individually defensible as spec violations, independent of any budget argument.

[kyle-sexton]

Cross-link: the per-field half of this is already covered — do not re-derive it.

skill-quality's check gained check 2b in 0.19.0 (#3119): DESC_FIELD_CAP=1024, the Agent Skills spec maximum for the description field alone, distinct from DESC_CHAR_CAP=1536 which bounds the assembled listing entry. It counts Unicode codepoints (not bytes, via the UTF-8 -> UTF-32BE iconv form) and carries a full four-part upstream-drift record.

That changelog already records 19 skills in this marketplace breaching 1024 (stated as a lower bound, measured with an extractor that reads slightly short of the gate's own). My independent count on the installed fleet is 20, consistent with that.

It is deliberately WARN, not FAIL, on measured evidence: claude plugin validate --strict (2.1.241) passes a 1248-char description clean, so the breach is latent for filesystem and plugin skills and hard only for a skill uploaded through the Skills API.

So the '20 entries over 1024' slice I suggested above is already visible to the repo's own tooling and already a deliberate WARN. It is not the untracked work I implied.

What remains genuinely untracked by this issue is the aggregate problem, which check 2b does not address and check-listing-budget.sh reports only advisorily:

• 163 listing-eligible skills at a mean of 740 chars against Anthropic's worked examples at ~176
• 120,723 chars total, 34% over a 90,000-char budget at skillListingBudgetFraction: 0.03
• fits at 0.05 with 29,277 headroom, so this is a headroom-and-growth problem rather than an active-truncation one for consumers on 0.05

Every one of those 163 is individually under the 1536 gate and 143 of them are under 1024 too. No per-skill check can catch this — it is only visible in the sum, which is exactly why check-listing-budget.sh is advisory and exits 0. That aggregate is the part worth acting on here.

[kyle-sexton]

Cross-reference: #3526 (description-driven auto-invocation evals) overlaps this issue's territory — a fleet-wide description rewrite should be evaluated against whatever that lands, since both change what the model matches on.

[kyle-sexton]

Claimed by the autonomous worker lane.

• instance: vm-worker-202609050257
• lease expires: 2026-09-05T04:15:00Z (60 min TTL, renewed while the worker is active)
• scope: implement, test, independently review, open a close-linked draft PR. This lane does not merge.

Label resolution caveat: this repository's .work-item-tracker.json has no role_labels map, so agent-ready was resolved by documented default rather than from config. Corroborated by the label's own description ("eligible for autonomous pickup from the frontier"), but flagged here for the record.

---

Generated by Claude Code

[kyle-sexton]

Escalated to the human floor by the autonomous worker lane — instance vm-worker-202609050257. Claim released, agent-ready removed, needs-human applied. No code changed, nothing pushed, worktree and branch cleaned up.

Why this stopped

Not feasibility — the worker measured the fleet with the repo's own tool and the target is physically reachable. It stopped because shipping it means inventing a fleet-wide skill-description convention and applying it to 182 files, which collides with three standing constraints already in this repo:

1. docs/conventions/native-references/README.md:184 — fleet-wide application is a reserved, separately gated sweep, one plugin per unit, never a single fleet-wide edit.
2. ADR 0004 D-3 (ratified, binding), docs/adr/0004-*.md:52 — no bulk sweep of plugins/**; findings land as checks in the plugin owning each surface.
3. skill-quality: measure and improve description-driven auto-invocation (eval-based) #3526, cross-linked from this issue's own comments, already owns this rewrite and gates it on an eval baseline that does not yet exist. It also records that aggregate listing-budget policy stays owned by claude-ops:audit-skill-visibility.

invocation-mode and seam-phrasing also bake required routing text into descriptions, so a blind trim would silently retract ratified doctrine.

Measurement recorded (real, origin/main @ 3ea592bb)

check-listing-budget.sh reports 182 listing-eligible skills / 135,596 chars. The issue was filed at 163 / 120,723, so the headline case is now 51% over, not 34% — the gap is widening. Protected single-quoted trigger phrases total 33,255 chars and only 1 skill of 182 exceeds 400 chars of them.

Decision needed

• (a) Authorize a new fleet-wide description convention plus a per-plugin gated sweep that supersedes native-references and ADR 0004 D-3; or
• (b) Sequence this behind skill-quality: measure and improve description-driven auto-invocation (eval-based) #3526 so the rewrite is eval-measured rather than blind; or
• (c) Reframe as consumer-side headroom (skillListingBudgetFraction: 0.05, where the fleet fits today) and close the source-trim half.

Labeling conflict worth fixing

This issue carried both agent-ready and work-class: structural. Those contradict: structural work is cross-cutting and hard to reverse, which is human-floor by definition and never autonomously eligible. Any item holding both will be claimed and then escalated by every lane instance in turn. Worth a tracker rule that makes the pair impossible.

---

Generated by Claude Code