Feature Request: SkillSearch — lazy-load skill descriptions like Tool Search does for MCP tools

Problem

Claude Code's Tool Search feature (v2.1.7+) brilliantly solves context bloat for MCP tools — when tool descriptions exceed 10% of context, it switches to name-only listing and lets Claude discover tool schemas on demand via ToolSearch. This achieves an 85% token reduction (e.g., 77K → 8.7K tokens).

Skills have no equivalent mechanism. Every installed skill's name + multi-line description is injected into the system-reminder at every session start, regardless of whether the skill will be used. The skills documentation claims progressive disclosure ("Claude reads these files only when needed"), but as documented in #14882, the full descriptions are loaded at startup.

Real-World Impact

| Metric | Value |
|--------|-------|
| Plugins installed | 22 (official + custom) |
| Skills listed at startup | 81+ entries |
| Custom skills on disk | 46 skills, 1.37MB total |
| Largest single skill | 100KB (gstack-ship) |
| Estimated listing cost | ~4-5K tokens (name + description × 81) |
| Context consumed at startup | ~15-20% of 1M window |
| Skills actually used per session | 2-3 |

The problem scales with ecosystem growth. As the plugin marketplace expands and users install more capabilities, the per-session tax grows linearly while per-session usage stays constant.

Current Workarounds

| Workaround | Limitation |
|------------|-----------|
| disabledPlugins per project in .claude/settings.json | Requires manual curation per repo; loses discoverability |
| Moving skills to ~/.claude/skills-inactive/ (#40770) | Clever hack, but shouldn't be necessary |
| Trimming skill descriptions | Degrades Claude's ability to match skills to tasks |

Proposed Solution: SkillSearch (mirrors Tool Search)

Apply the same pattern that already works for MCP tools:

Tier 1: Name-only listing (always loaded)

Available skills:
- standup — Generate daily stand-up entry from git activity
- weekly-status — Generate weekly status report for management
- meeting-recap — Process meeting transcript into structured recap
- gstack-ship — Ship workflow with tests, review, PR
... (81 entries, ~50-100 tokens each)

Cost: ~4-8K tokens total (vs. current ~16-20K+ with descriptions)

Tier 2: Description discovery (on demand via SkillSearch)
When Claude considers invoking a skill, it calls SkillSearch("standup") to retrieve the full description and trigger patterns — exactly like ToolSearch works for MCP tool schemas.

Tier 3: Full skill body (on invoke via Skill tool)
Already works this way — the Skill tool loads the full SKILL.md content only when explicitly invoked. No change needed.

Why This Works

• Proven pattern: Tool Search already validates this architecture in production
• Minimal new surface: One new internal tool (SkillSearch) mirroring ToolSearch
• Backwards compatible: No change to skill authoring, SKILL.md format, or plugin structure
• Scales indefinitely: 100+ skills would cost the same as 10 at startup
• Preserves discoverability: Claude still knows all skill names and can search descriptions when relevant

Alternative: Activation Events (VS Code model)

A complementary enhancement: let skills declare activation triggers in frontmatter:

---
name: xlsx-editor
description: Edit Excel spreadsheets
activatesOn: ["*.xlsx", "*.csv", "spreadsheet", "excel"]
---

Skills only inject their description when the session context matches a trigger. This is more surgical than SkillSearch but requires more design surface. Could be a Phase 2 enhancement.

Related Issues

• #14882 — Skills consume full token count at startup (bug report, 11 upvotes)
• #40770 — Skill Loader workaround for on-demand management
• #39854 — Context-aware instruction loading
• #41068 — Skill-Driven On-Demand MCP & Tool Loading
• #30423 — Skill profiles: role-based scoping
• #7336 — Original MCP lazy-loading request (implemented as Tool Search)

Environment

• Claude Code v2.1.92
• macOS Darwin 25.3.0
• Claude Opus 4.6 (1M context)
• 22 plugins, 46 custom skills