Feature request: lazy-load agent descriptions and skill names to reduce context usage
Problem
All agent .md files from ~/.claude/agents/ and all command/skill names from ~/.claude/commands/ are injected into every session's system prompt, regardless of whether they'll be used.
For a typical power-user setup:
- 13 GSD agents (~5,000 tokens in descriptions alone)
- 27
gsd:*skill entries (~800 tokens) - Other custom agents (~1,000 tokens)
- Total: ~7,000 tokens wasted per session when these tools aren't used
Combined with CLAUDE.md files, a user can start at 20%+ context usage before typing anything. This directly reduces the useful working context for actual tasks.
Proposed solution
- Agent descriptions: Only inject agent names into the Task tool definition (e.g.,
"gsd-planner": "GSD planning agent"). Load the full.mddescription only when the agent is actually spawned via the Task tool. The spawning logic already reads the file — the system prompt doesn't need the full description.
- Skill/command names: Consider a tiered approach:
- Always show: project-level commands (likely relevant)
- On-demand: global commands and plugin skills (show name only, load description when invoked)
- Optional config: Allow users to mark agents/skills as
"lazy": truein settings or via a convention (e.g.,.claude/agents-lazy/directory), so they're available but not loaded until needed.
Current workaround
Users must manually move files to disabled folders and toggle them back, which defeats the purpose of having an integrated tool ecosystem.
Impact
This would significantly improve context efficiency for users with rich tool setups (GSD, custom agents, multiple skills) without losing any functionality. The tools would still be available — just not consuming context until needed.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗