Feature request: lazy-load agent descriptions and skill names to reduce context usage

Resolved 💬 2 comments Opened Feb 2, 2026 by mercierj Closed Feb 2, 2026

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

  1. Agent descriptions: Only inject agent names into the Task tool definition (e.g., "gsd-planner": "GSD planning agent"). Load the full .md description 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.
  1. 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)
  1. Optional config: Allow users to mark agents/skills as "lazy": true in 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.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗