| name | context-management |
| description | Guidance on when to use subagents to keep the main conversation context clean. Use this skill when you're about to do research that involves reading many files (5+), exploring unfamiliar parts of a codebase, investigating a bug across multiple modules, or answering a broad question that requires gathering information from scattered sources. Also use when the user asks you to "look into", "investigate", "explore", or "find out how X works" — these are signals that the work is research, not implementation, and a subagent can do it without bloating the main context. |
Context Management: When to Use Subagents
The main conversation's context window is a finite, precious resource. Every file you read, every
command you run, every tool result — it all accumulates. When context fills up, performance
degrades: you start forgetting earlier instructions, losing track of decisions, and making mistakes.
Subagents run in their own context window. They can read dozens of files, explore broadly, and
then report back a concise summary. The main conversation only sees the summary.
When to suggest a subagent
Before starting research that will touch many files, pause and consider whether a subagent would
be more efficient. Signals:
- You're about to read 5+ files to answer a question
- The user asked you to "investigate", "look into", "explore", or "find out how X works"
- You need to search across a codebase for patterns, usages, or conventions
- You're debugging and need to trace a call chain through multiple modules
- The user asked a broad question about how something works
When NOT to use a subagent
- You already know which 1-2 files to look at
- The user is asking you to implement something (they need the context in the main conversation)
- The research is trivial (a single grep or glob)
- The user is mid-conversation about a topic and the files are already in context
How to suggest it
Don't just silently spawn a subagent. Mention it briefly:
- "That'll involve reading through several files — I'll use a subagent to investigate and report back."
- "Let me delegate that research to a subagent so we keep this context clean."
How to structure the delegation
Give the subagent a specific research question, not a vague directive:
Good: "Find all places where authentication tokens are refreshed, trace the refresh flow, and
summarize the mechanism including which files are involved."
Bad: "Look at the auth code."
The subagent should return a summary with:
- The answer to the research question
- Key file paths and line numbers for reference
- Any decisions or tradeoffs it noticed
After the subagent reports back
Summarize the findings for the user concisely. Don't dump the full subagent report — distill it
to what's relevant for the current task. The user can ask follow-up questions if they need more
detail.
