Listing-budget decision: full-install aggregate is 86.5k chars (~10.8x the default budget)

[kyle-sexton]

Context

Menu item #4 of the Boris-talk digest: every always-loaded skill description is a per-turn tax, so the marketplace's full-install listing surface is itself an unhobbling concern. This is the report-only analysis; the target decision (digest questions.md #4) is the operator's and gates any remediation.

Current numbers, measured on main (19a3f7b3) with skill-quality's check-listing-budget.sh pooled over plugins/*/skills:

• 134 listing-eligible skills across 61 plugin roots (skills with disable-model-invocation: true excluded — they spend no budget).
• Aggregate: 86,499 chars ≈ 10.8x the 8,000-char documented default budget (SLASH_COMMAND_TOOL_CHAR_BUDGET fallback, ~1% of context window). Live, Claude Code drops the least-invoked skills' descriptions to name-only when this overflows — silently degrading auto-invocation for the tail.
• Advisory only: the live figure depends on the consumer's model window, skillListingBudgetFraction, and skillOverrides; /doctor in a live session is the authority. The estimate is an upper bound for full-install consumers.

Top contributors (entry chars):

chars	skill	root
1468	babysit-loop	plugins/source-control/skills
1197	audit-instructions	plugins/claude-config/skills
1161	audit-derivability	plugins/docs-hygiene/skills
1116	running-retro	plugins/session-flow/skills
1072	reconcile	plugins/session-flow/skills
1058	clarify	plugins/adhd/skills
1057	improve	plugins/architecture/skills
1054	script-the-deterministic-work	plugins/discipline/skills
1028	audit-answers	plugins/planning/skills
1022	reuse-or-replace	plugins/discipline/skills

Context for the decision: a full install is ~86k chars ≈ 21–22k tokens of always-loaded listing text before any work starts. But installs are per-plugin selective — no consumer is forced to take all 61 roots — and per-skill entries are already capped at 1,536 chars by the skill-quality per-skill gate (none currently exceed it).

Proposed work — the operator picks one (questions.md #4)

1. Accept-as-is with rationale: installs are selective; the per-skill 1,536 cap plus the advisory aggregate report is enough. Record the rationale here and close.
2. Tighten the worst descriptions: mechanical pass over the top-N contributors (e.g. everything >1,000 chars — 10 skills) trimming toward the trigger phrases that earn their keep. No structural change.
3. Curated starter bundles / per-plugin caps: define install sets or a hard per-plugin budget in doctrine. Structural; needs its own design pass.

A quarterly report-only "listing-budget watch" recurring routine is being wired separately (self-maintenance pilot) so drift is observed regardless of which option is chosen.

Acceptance criteria

• Operator has chosen among the three options above (or named a fourth) and the choice is recorded on this issue.
• If option 2/3: follow-up work items exist for the remediation; if option 1: rationale recorded and this issue closed.

References

• knowledge-corpus digest slice boris-cherny-we-cut-80-of-claude-code-s-qyPCVqFUyDo — recommendations/menu.md ci: onboard to the CI platform (ci-workflows + standards) #4, recommendations/questions.md ci: onboard to the CI platform (ci-workflows + standards) #4, research/findings/repo-instruction-surface.md (baseline: 184 skills / ~28k tokens; live count now 134 listing-eligible after disable-model-invocation exclusions)
• plugins/skill-quality/skills/check — listing-budget action (the measurement tool; advisory by design)
• docs/PLUGIN-PHILOSOPHY.md — "Instruction economy"

[kyle-sexton]

Operator decision recorded (2026-08-08 decision round): option 2 executed now, option 3 pursued as follow-on — "make sure all adhere, focus on the worst first, maybe also do #3."

• Option 2 (tighten the worst): PR refactor: tighten the 10 worst skill-listing descriptions toward the shared budget #2054 trims all ten >1,000-char entries (10,193 → 7,750 chars across the ten, −2,499 net vs its base after restoring the merge-authority invariants a review round flagged), every quoted trigger phrase preserved (skill-quality check-3 verified per skill), catalog/cheat-sheet regenerated. Post-change full-install aggregate: 85,650 chars over 136 listing-eligible skills / 62 roots (~10.7x the 8k default) — advisory, as the issue scoped.
• Option 3 (structural): filed as Listing-budget option 3: curated starter bundles and a per-plugin listing budget (design) #2034 — curated starter bundles (documentation-level) + a per-plugin listing ceiling enforced advisory-first through skill-quality's check, with [Maintenance] Listing-budget watch: report the shared aggregate and drift #2023's watch gaining per-plugin subtotals. Bundle membership and the ceiling value are named there as operator calls.
• Watch wiring: [Maintenance] Listing-budget watch: report the shared aggregate and drift #2023's first cycle was discharged today with the baseline/post-change numbers, so drift is now observed on the standing cadence regardless.

This issue closes when #2054 merges (acceptance criteria: decision recorded ✓, follow-up work items exist ✓).

[kyle-sexton]

Closing: acceptance criteria met. Option decision recorded above (option 2 + option 3); option 2 executed and merged (#2054 — ten entries trimmed, trigger phrases preserved, post-change aggregate 85,650 chars / ~10.7x advisory); option 3 tracked in #2034; the standing watch (#2023) discharged its first cycle with these numbers and observes drift going forward.