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

[jvalenzano]

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

• Skills consume full token count at startup instead of progressive disclosure (frontmatter only) #14882 — Skills consume full token count at startup (bug report, 11 upvotes)
• Skill Loader: workaround for on-demand skill management #40770 — Skill Loader workaround for on-demand management
• Feature request: Context-aware instruction loading (lazy-load instructions by action type) #39854 — Context-aware instruction loading
• [FEATURE] Skill-Driven On-Demand MCP & Tool Loading #41068 — Skill-Driven On-Demand MCP & Tool Loading
• [FEATURE] Skill profiles: role-based scoping of active skills #30423 — Skill profiles: role-based scoping
• Feature Request: Lazy Loading for MCP Servers and Tools (95% context reduction possible) #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

[github-actions]

Found 3 possible duplicate issues:

1. Feature Request: Deferred Loading for Skills (SkillSearch, like ToolSearch) #29711
2. Lazy-load skill descriptions instead of injecting all into system prompt #28398
3. Feature: Deferred skill discovery to reduce context window overhead #42650

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[GMedlin]

I’d like to see this too. Or a way to create Claude Code agents that only have access to certain skills so that the main Claude Code session doesn’t need to have them all, but knows what agent to call for them.

[PettHa]

Data point from a heavy-skill setup on Claude Code v2.1.119:

• 47 skills (1 user + 35 project + 11 plugin) + 11 subagents listed in every system-reminder block
• ~10K tokens of metadata injected per turn (scaling from the 81-skill numbers in the OP)
• 1-2 skills typically invoked per session

These aren't experimental skills — they're production workflow captures (deploy, prod-log triage, security audits, schema migrations, browser tests). The library grows because each new skill makes the tool meaningfully better at recurring work.

The catch: each new skill also makes the next session start later in the context budget, even though only a handful ever get invoked. Directly discourages the ecosystem growth this design solves for.

Worth linking #44536 (filed after this) — generalizes the same pattern to skills + MCP + rules + instructions. Shipping this issue first is the cleaner incremental path.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.