[FEATURE] Per-agent skill-listing visibility scoping (honor agent `skills:` field as a visibility filter)

Preflight Checklist

• [x] Searched existing requests — clustered with #39579 (auto-closed for inactivity, never received a maintainer response; closing bot invited refiling), #44952, #12633, #54089, #46311. This ask is intentionally narrower than #39579 (existing-field semantic upgrade vs. skill-loading redesign) and complementary to #54089 (skill-side when:).
• [x] Single feature request.

Problem Statement

The skill-listing budget (skillListingBudgetFraction, default 0.01) applies globally across all agents. With a non-trivial catalog, truncation is structural, not a tuning issue.

Empirical baseline from a real-world catalog (~/.claude/skills/ with 1141 skills + plugin-pool skills, default 1% budget on 1M-context Opus):

| Metric | Value |
|---|---|
| Catalog size | 1141 local + plugin-pool skills |
| Theoretical full-listing cost | ~340k chars |
| Available budget (1% of 1M) | ~10k chars |
| Overshoot | ~34× |
| Runtime warning | 1262 descriptions dropped (full descriptions kept for most-used skills) (49%/1% of context) |

The <available_skills> listing is identical across all agents. Whether I dispatch a python-architect, a book-writer, or an sre, the same 1262 descriptions drop per session, and which descriptions survive is determined by per-user skillUsage history — not by what the active agent actually needs.

Per claude-architecture/SKILL.md § Inheritance Model: "Skills catalog [has] same visibility across main agent and subagents." The agent skills: frontmatter field bundles skills as documentary intent but does not filter the global listing.

Proposed Solution

Make the existing agent skills: frontmatter field act as a visibility filter (opt-in, backward-compatible):

# ~/.claude/agents/sre.md
---
name: sre
description: SRE incident response
skills:
  - sre-runbook-automation
  - kubernetes-manifests
  - incident-response
  - sre-monitoring
visibility-scope: declared   # NEW: opt-in flag
---

When this agent is the active context (Agent-tool dispatch or claude --agent sre), the skill-listing budget is consumed by:

• the declared skills: set, plus
• a small set of always-on globals (configurable; defaults to core workflow skills like workflow-do, git, claude-subprocess)

All other skills are omitted from the listing. They remain installed, invocable directly by name (slash command or Skill tool), and inheritable into nested subagents per their own scoping.

Optional inverse: an agents: field on SKILL.md frontmatter declaring which agents the skill is visible to (skill-side scoping), for cases where the skill-author knows the right scope better than every agent-author.

Backward compatibility: agents without the opt-in flag behave exactly as today (global visibility). Existing skills: fields keep their current bundling semantics; the new flag adds the filter behavior.

Alternative Solutions

| Alternative | Limitation |
|---|---|
| Raise skillListingBudgetFraction to 0.1 | Costs ~98k tokens per session at this catalog scale; burns rate limits |
| Use skillOverrides to globally hide skills | Binary on/off — can't be visible-to-A-only / hidden-from-B |
| skillUsage most-used prioritization | Per-user, per-machine; frequently-used-by-context-A skills crowd out context-B's needs; cold-start = 0 |
| when: SKILL.md field (#54089) | Complementary — skill-side context gating; doesn't address agent-driven scoping |
| Hide-from-main-agent (#12633) | Inverse direction; partial coverage |
| Per-skill plugin enable/disable (#47747) | Install-time, not runtime |
| Run multiple claude instances with different plugin sets | Doesn't help in-session subagent dispatches |

Priority

Medium — Would be very helpful (quality issue, not a hard blocker; degrades agent routing decisions silently)

Feature Category

Configuration and settings

Use Case Example

1. I have 1141 skills in ~/.claude/skills/ covering writing pipelines (~80 children's-book skills via cultural / language / tradition bundling, screenplay, journalism), language toolchains (10+ languages × testing / async / packaging), ops (CI/CD, SRE, infra), brand/marketing, finance, and more.
2. I dispatch a python-architect agent to design a Python service architecture.
3. Today: that agent's listing includes all skills + plugin skills. ~1262 descriptions drop. Which descriptions survive depends on skillUsage history that has nothing to do with this dispatch. The agent may not see python-uv, python-testing, python-forward-refs if my last 50 sessions were writing children's books.
4. With this feature: python-architect's skills: field declares the relevant subset (~10–15 skills); only those + globals appear in the listing; descriptions fit comfortably; the agent makes informed routing decisions.
5. The same dispatch on a fresh machine (cold-start skillUsage) becomes deterministic instead of usage-history-dependent.

Additional Context

• skillListingBudgetFraction was documented in v2.1.131 (per recent docs additions). Many users likely don't realize how aggressive truncation is at scale — the 49% / 1% gap is invisible until you hit it.
• Per-skill description compression discipline (e.g., 350-char hard ceilings with audit governance) recovers a constant factor at most. Only context-gated listing addresses the structural overshoot.
• The 70% context-fill reasoning-quality fracture point cited in #54089 lands here too — 49% from skill descriptions alone leaves very little headroom for actual work.
• Related cluster:
• #39579 (auto-closed inactive 2026-04-30; broader scope; never received a maintainer response — bot invited refiling)
• #44952 (open; TeamCreate-specific variant)
• #12633 (open; skill-side hide-from-main, inverse direction)
• #54089 (open; complementary when: skill-frontmatter mechanism)
• #46311 (open; bug — skills: doesn't inject content into subagent context, indicating the field is partially-implemented today)

Environment: macOS 26.3 (arm64) / Claude Code 2.1.131