Skill-listing context budget: document trim policy + expose a registered/dropped diagnostic + supported suppression flag

Problem Statement

When a large plugin marketplace is installed, Claude Code silently trims the set of skills registered in a session's skill listing, with no diagnostic and no documented policy.

Observed (Claude Code 2.1.x, Windows 11): a session against a private marketplace with ~230 available skills (counted as plugins/*/skills/*/SKILL.md, excluding deprecated stubs) registered only 123 skills in the session listing — roughly 47% of the catalog was not visible to the model. There is:

• no warning or diagnostic anywhere (claude doctor, /skills, session start output all silent);
• no documentation of the trim policy — we cannot tell whether selection is by plugin, listing order, description length, or an internal character budget;
• no way to observe the trim except manually diffing the session's registered listing against the on-disk skill count.

The practical failure mode is the worst kind: agents stop seeing skills that exist, and then hallucinate or re-derive workflows the marketplace already encodes — with nothing telling the operator why.

This is a sibling of #78270 (a SKILL.md description with an unquoted ": " is silently dropped from the listing/slash menu with no diagnostic, while remaining invokable by exact name via the Skill tool). That bug and this trim are two independent silent-drop channels with the same undiagnosability. #78270 also demonstrates that "registered but unlisted" skills still work when invoked by exact name — which suggests listing suppression is already mechanically possible, just not exposed as a supported contract.

Proposed Solution

Three concrete asks, any one of which materially helps:

1. Document the trim policy. Publish what the skill-listing context budget is and how skills are selected/ordered/truncated when the installed set exceeds it (per-skill description truncation limits included). Marketplace maintainers cannot do capacity planning against an undocumented cutoff.
2. Expose a registered-vs-dropped diagnostic. A per-session report — in claude doctor and/or /skills — listing which installed skills were registered and which were dropped from the listing (and why: budget, parse failure, etc.). "Fail loud" for the budget channel, exactly as #78270 asks for the parse-failure channel.
3. A supported listing-suppression flag. A frontmatter field (e.g. listed: false) or plugin-level setting meaning "register but don't list" — the skill stays invokable by exact plugin:skill name but spends no listing budget. This lets marketplaces manage their own budget deliberately (e.g. hide incubating/experimental skills) instead of having the trim choose for them. Today the only way to get this behavior is to exploit the #78270 parse bug, which nobody should do.

Reproduction posture

Install any marketplace with 200+ skills across multiple plugins; start a session; compare the session's skill listing against the on-disk SKILL.md count. Registered count lands well below available with no diagnostic. Environment: Claude Code 2.1.x, Windows 11 (also reproduced under WSL2).

Alternative Solutions

We currently plan to instrument this ourselves (a SessionStart hook diffing registered-vs-available and logging the delta), and to manage budget via per-plugin enable/disable profiles — but both are workarounds for a policy that only the CLI can see and only the CLI can report on.