Skip to content

perf(skills): finish cutting the shared skill-listing cost after #4555 #4657

Closed

Description

@kyle-sexton

Problem

The melodic-software skills overflow the shared skill-listing budget on 200k-window models, and
the fix is at the source: shorter descriptions. Two follow-ups have landed. PR #4376 (claude-ops
0.59.1) fixed audit-skill-visibility --installed counting never-enabled plugins as enabled.
PR #4555 (discipline 0.14.9, #4552) trimmed 13 discipline descriptions to 500 characters or fewer.
The work below is what remains, split into three child issues:

  1. Trim descriptions in the other heavy plugins (child: description trims).
  2. Decide whether any skill should take disable-model-invocation: true to save listing cost,
    which conflicts with a standing convention (child: needs-decision).
  3. Align the remaining surfaces with the observed enablement rule: an installed plugin that no
    enabledPlugins scope names does not load. The surfaces are levers.json:257, the claude-ops
    fleet-state docs, and the non-Boolean enabledPlugins handling (child: enablement rule).

Evidence

Measured numbers, all in source description characters (description + when_to_use, skills
without disable-model-invocation: true):

  • bash plugins/skill-quality/scripts/check-listing-budget.sh plugins/*/skills at a6ba321e1
    (2026-09-27): 208 listing-eligible skills across 80 roots, 152,297 chars. That is about 19x the
    8,000-char default the script assumes, and the script calls it an estimate. A separate parse
    at origin/main 946caf11 gives 152,182.
  • The operator machine measured with audit-skill-visibility --installed on Claude Code 2.1.270
    (item, Part C). The 63 explicitly enabled plugins had 166 model-visible skills totaling 108,992
    chars. Budget at skillListingBudgetFraction: 0.05 on a 1M window, at 4 bytes per token, is
    200,000 chars, so the listing fits. On a 200k window it is 40,000 chars and overflows by 68,992.
    At the default 0.01 on a 1M window it is also 40,000. A live 1M session at 0.05 showed every
    claude-ops description in full, so the fit was observed, not only computed.
  • Fitting 108,992 chars into a 200k window would need a fraction of about 0.14 to 0.18, so
    raising the fraction does not help there. Source trims do. That case covers sonnet and haiku
    subagents.
  • skillListingMaxDescChars default is 1,536, so no description is capped; every character
    counts.
  • The settings reference now documents the skillListingBudgetFraction default as 0.01 ("which
    reserves 1% of the context window"), re-fetched 2026-09-27. The item said it had no documented
    default; that is superseded.
  • The item's Plugins > Stats tab figures (about 15,260, about 5,500, about 1,960) have no
    documented unit. Do not use them or convert them to tokens.

The per-plugin table is in the trims child.

Proposed approach

Work the three children independently. The operator decided on 2026-09-25 (inbox loop h17):

  • Trim the listing per plugin, with no renames and no skill merges.
  • Never set disable-model-invocation on a skill that the PR ready flow, extract-ssot, or
    audit-pass invokes through the Skill tool.

The item also proposed three things that this decision rules out. Consolidating the four
docs-hygiene:audit-* skills into one moded audit is a merge, so it is declined. Folding the
-deep discipline variants into their base skills is also a merge, so it is declined. Disabling
unused vendor plugins to save listing cost is dropped because those plugins never loaded.

Acceptance criteria

  • All three child issues closed or explicitly declined.
  • check-listing-budget.sh plugins/*/skills aggregate recorded before and after in each trims
    PR.

Constraints and gotchas

  • "Never invoked" does not prove a skill is useless. This is a deliberate pass, not bulk deletion.
  • Leave these to other lanes, not this repo:
    • The dotfiles reconciliation (the item's Part B) duplicates local item 20260912-222500.
    • The autoMode.classifyAllShell probe needs an SW2030 session.

Context

Source: local handoff item 20260923-182500-skill-listing-context-cost-remainder-after-4376.md,
retired into this issue and its children.

Related:

Activity

  1. 6 remaining items

  2. kyle-sexton commented on Sep 29, 2026

    @kyle-sexton
    MemberAuthor

    From the 2026-09-29 audit of the Cursor run. Reopened.

    #4774's body said "Does not close #4657", yet the epic auto-closed at 64cdc57 (github-actions warned 13 minutes before merge). AC1 (all three children closed or declined) did not hold then. State today (gh issue view, 2026-09-29): #4659 closed 2026-09-28, #4660 closed 2026-09-29 (by #5202), #4661 still open. The audit report's "link #4660 as its tracker" is stale.

    So AC1 does not yet hold. Reopened until #4661 is closed or declined. Children: #4659, #4660, #4661. No code change here.

  3. kyle-sexton commented on Oct 1, 2026

    @kyle-sexton
    MemberAuthor

    Owner decision (2026-10-01): accepted the recommendation ("accept all recommendations" and "I want you to do all of this for me", the owner's reply to the list that named this item).

    Criterion 2 is waived: seven merged trims PRs (#4776, #4930, #4931, #4954, #4955, #4958, #5258) never recorded the before/after listing-budget aggregate, and those PR bodies are history. Every child (#4659, #4660, #4661) is closed as completed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions