--- title: "07 — Subagents — Isolated Expert Bubbles for Focused Work" uid: subagents tags: ["roadmap:claude-code", "context-management", "multi-agent", "agents", "claude-code", "subagents"] excerpt: "A subagent is an isolated context bubble with its own system prompt and restricted tools that returns a summary — keeping verbose research out of your main thread." date: 2026-08-13T03:28:22+0000 source: https://www.aveshina.my.id/en/blog/subagents --- "Just more agents" described subagents without explaining why they exist. The reason is context hygiene: **a subagent is an isolated context bubble with its own system prompt and restricted tools, that handles a focused task and returns a summary — so the main conversation stays clean.** [1] The whole point is context hygiene: the verbose research and intermediate logs live in the bubble, not in my primary thread. The framing that clicked is to think of subagents as a context-management technique, not a parallelism feature (parallelism is a separate benefit, covered in the scaling post). The main agent has one context window, and it fills up. When a task involves reading twenty files to find one fact, the _reading_ shouldn't pollute the main thread — only the _fact_ should come back. A subagent is the bubble that does the reading in its own clean window and returns just the conclusion [1][2]. ## What a subagent actually is The roadmap's definition is precise: a specialized AI assistant that functions as an independent team member to handle a focused task on behalf of the main agent [1]. Three properties matter: - **Its own isolated context window.** It starts with a clean slate. Whatever it reads, runs, or generates stays in its bubble. - **A tailored system prompt.** Defined by a markdown file in .claude/agents/ with YAML frontmatter specifying its name, description, model, and a restricted set of tools [3]. - **A summary return.** When it finishes, it hands back a summary to the main agent — not the full transcript. The main thread stays lean. ```figure ``` ## Creating a subagent The recipe is a markdown file in .claude/agents/ with YAML frontmatter [3]. The frontmatter pins the four things that define the bubble: - **name** — what the main agent calls on. - **description** — when it should be invoked (the discovery trigger, same idea as a skill's). - **model** — which model powers it. A common pattern is a cheaper/faster model (Haiku) for a scan-the-logs subagent, the strong model (Opus) for an architecture-planning one. - **tools** — the restricted set. This is the safety lever: a "research only" subagent gets Read and Grep but not Edit or Bash, so it literally cannot change anything. The /agents command manages them inside a session, and the roadmap frames it as the transition from a single-assistant model to a multi-agent workflow — delegating security auditing, unit testing, or architectural planning to specialists with isolated windows and tailored prompts [4]. ## Why this is a context technique The reason subagents are more than a curiosity is the context math. The main agent re-reads its entire conversation every turn (that's how it maintains state). If I let it read twenty files inline, those file contents sit in the context for the rest of the session, inflating every subsequent turn's token cost and accelerating context rot. If instead a subagent reads those twenty files in its own window and returns a three-line summary, the main thread carries three lines — not twenty files [2]. The roadmap states this directly: subagents are an architectural tool that manages the context window by practicing "selective attention," keeping the main conversation lean while specialized tasks remain high-precision [2]. The pattern I reach for: any task whose _inputs_ are large but whose _conclusion_ is small is a subagent candidate. "Find the bug," "audit these logs," "summarize this dependency" — large reads, small answers. ## The slash commands around them A few commands live in the subagent orbit: - **/agents** — create, configure, orchestrate subagents; switches to a multi-agent workflow [4]. - **/context** — a diagnostic grid showing how the model's context window is currently allocated: every file, turn, and tool result, and which consume tokens [5]. My check before deciding to delegate. - **/compact** — summarizes the conversation to free context (an alternative when I don't want to spawn a subagent) [6]. - **/init** and **/memory** — covered in the CLAUDE.md post; they shape the persistent memory the main agent (and any subagent) starts from. The way of thinking: /context tells me _when_ to delegate, /agents is _how_, and the subagent's restricted tools frontmatter is _how much rope_ the delegate gets. ## How I use this The habit these notes left me with is a delegation test on every large-read task. Before I let the main agent read a directory or a long log, I ask: *do I need the file contents later, or just the conclusion?* If just the conclusion, it goes to a subagent with a tight tool restriction. Research subagents get Read + Grep (no edits possible); planning subagents get the strong model and read-only tools. The main thread stays short, costs stay predictable, and the one thing I lose — seeing the intermediate steps — is exactly the thing I didn't want cluttering the conversation anyway. ## References [1] Anthropic, "Create custom subagents," Claude Code Docs, 2025. [Online]. Available: [https://code.claude.com/docs/en/sub-agents](https://code.claude.com/docs/en/sub-agents) [2] Anthropic, "Claude Code Subagents: Complete Guide to Multi-Agent Architecture," 2025. [Online]. Available: [https://wmedia.es/en/writing/claude-code-subagents-guide-ai](https://wmedia.es/en/writing/claude-code-subagents-guide-ai) [3] Anthropic, "Create custom subagents — agent file format," Claude Code Docs, 2025. [Online]. Available: [https://code.claude.com/docs/en/sub-agents](https://code.claude.com/docs/en/sub-agents) [4] Anthropic, "Interactive mode — /agents," Claude Code Docs, 2025. [Online]. Available: [https://code.claude.com/docs/en/interactive-mode](https://code.claude.com/docs/en/interactive-mode) [5] Anthropic, "Interactive mode — /context," Claude Code Docs, 2025. [Online]. Available: [https://code.claude.com/docs/en/interactive-mode](https://code.claude.com/docs/en/interactive-mode) [6] Anthropic, "Interactive mode — /compact," Claude Code Docs, 2025. [Online]. Available: [https://code.claude.com/docs/en/interactive-mode](https://code.claude.com/docs/en/interactive-mode) ```quiz Q: What are the three defining properties of a subagent? - A shared context with the main agent, full tool access, returns the full transcript - Its own isolated context window, a tailored system prompt with restricted tools, and returns only a summary correct: 1 explain: A subagent runs in a clean bubble with its own prompt and a restricted toolset, and hands back a summary — not the verbose intermediate work, which stays in the bubble. Q: Why is delegating a large-read task to a subagent a context win? - It makes the model run faster overall - The large file contents stay in the bubble; only the small conclusion enters the main thread, which is re-read every turn correct: 1 explain: The main agent re-reads its whole context each turn. Keeping large reads in a subagent means the main thread carries a short summary instead of twenty files, saving tokens and slowing context rot. Q: In a subagent's YAML frontmatter, what does the `tools` field control? - Which model the subagent uses - The restricted set of tools the subagent can call (the safety lever) correct: 1 explain: `tools` is the restriction set — e.g. a research subagent gets Read + Grep but no Edit or Bash, so it literally cannot change anything. The `model` field is separate. Q: When should a task go to a subagent rather than the main agent? - When its inputs are large but its conclusion is small - Whenever the task is important correct: 0 explain: The delegation test is about input/output size: large reads with a small conclusion are ideal subagent work, because the verbose part stays isolated and only the conclusion returns. Q: What does the /context command show you? - A grid of how the context window is currently allocated — which files, turns, and tool results consume tokens - A list of all subagents available correct: 0 explain: /context is the diagnostic for context allocation. It tells you when delegation is worthwhile by showing exactly what's consuming the window. ```