[FEATURE] Hierarchical skill discovery to reduce skill-list metadata overhead

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Claude Code already supports dynamic or progressive skill loading, which is great: the full skill body is loaded only when it's needed. However, Claude still needs metadata (the name and description) for every installed skill in order to determine which skills might be relevant. As the plugin and skill ecosystem grows, this metadata index becomes a large context overhead. For example, if a user has plugins installed for Vercel, React, Flutter, iOS, Python, design systems and CI/CD, a session about a Vercel deployment still pays the metadata cost of many unrelated skills. Even when the full skill bodies are lazy loaded, the flat skill list becomes the bottleneck.

Proposed Solution

Add a hierarchical discovery layer before exposing individual skills to the model. Instead of injecting the name and description of every installed skill at once, include only plugin-level or capability-group metadata in the initial context. The model selects the relevant plugin or group, then loads that plugin's skill list only if needed. For example, list 'Vercel: deployment, preview environments, project configuration', 'React: components, hooks, state management', 'Flutter: widgets, build errors', 'iOS: Swift, App Intents'. If the user asks about a Vercel preview deployment issue, Claude expands only the Vercel plugin's skill list. This reduces always-on context usage from all skills to a small set of plugins/capabilities. Possible implementations include plugin-level metadata, nested capability groups for large plugins, and activation profiles to preselect relevant plugins.

Alternative Solutions

Previous proposals, such as adding a when: frontmatter condition (#54089), focus on gating individual skills at runtime. While valuable, this still requires listing every skill's metadata. This proposal operates at the plugin or capability group level to reduce metadata overhead. Another alternative is reducing installed skills via minimal install flags or manual disabled lists, but this loses capabilities permanently and requires user maintenance. Hierarchical discovery preserves capabilities while trimming metadata.

Priority

High - Significant impact on productivity

Feature Category

Performance and speed

Use Case Example

Scenario: A developer has plugins installed for Vercel, React, Flutter, iOS, Python, design systems, and CI/CD because they work across multiple projects. They open Claude Code to debug a Vercel deployment problem. With the current flat skill list, the session includes the name and description of all installed skills, consuming thousands of tokens before any work begins. Claude may even route to unrelated skills. With hierarchical discovery, the initial context lists only high-level plugin capabilities (e.g., "Vercel: deployment, preview, builds") and the Vercel plugin's skill list is expanded only when needed. This saves context and reduces cognitive load.

Additional Context

This issue builds on the idea of context gating (#54089) but focuses on plugin-level grouping. Issue #54089 was closed as stale, yet the underlying problem remains as skill inventories and plugin ecosystems grow. The proposal also takes inspiration from hierarchical tool routing patterns in research (e.g., "Tool Attention Is All You Need", "MCP-Zero", etc.), which show that selective tool exposure reduces token overhead and improves routing accuracy. The hierarchical discovery pattern (plugin -> skill list -> skill body) is a natural extension of this idea for skills.