claude-code - 💡(How to fix) Fix Feature request: lazy skill loading for plugins with many skills [1 participants]

Problem

Claude Code loads all skill description: fields from every installed plugin into the system prompt on every turn. For plugins with many skills (e.g., 79 skills), this adds ~800-1,200 words of ambient token burn regardless of which skill is being used.

We've already compressed our descriptions from ~2,900 to 822 words (72% reduction), but the fundamental issue is that all descriptions load on every turn even when most are irrelevant.

Proposed Solutions

1. Lazy Skill Loading (preferred)

Load skill descriptions on demand rather than all-at-once:

• Subagent-scoped: When a subagent is spawned with subagent_type: "plugin:agent-name", only load descriptions for skills listed in that agent's file — not all plugin skills.
• Recency-scoped: In the main thread, load descriptions only for skills invoked in the last N turns. On first turn, load only skills with argument-hint: in frontmatter (user-invocable entry points).

2. Description Truncation (fallback)

If lazy loading isn't feasible, truncate skill descriptions to the first sentence in the system prompt. The full description loads when the skill is actually invoked via the Skill tool. Preserves routing signals while cutting ambient burn by ~60%.

3. Spec Deduplication Across Subagents

When multiple subagents in the same session read the same file, subsequent reads could serve from a session-level cache with a marker instead of re-reading. Prompt caching helps at the API level, but each subagent still processes the full content in its context window.

Impact

For a plugin with 79 skills, lazy loading would eliminate ~800-1,200 words of ambient context per turn — the single highest-impact optimization available beyond what plugin authors can do themselves.

Context

This came out of a token optimization effort on a Claude Code plugin. We trimmed instruction files from 8,734 to 7,754 lines and descriptions from 2,900 to 822 words. The remaining ambient burn from the skill menu is now the dominant token cost and is outside plugin-author control.