Claude Code Subagents: Delegating Work to Its Own Context

Claude Code doesn't have to carry a long job by itself. It can hand pieces off to subagents, helper workers of its own. The device exists because of a real limit: the longer a conversation runs, the more its context window fills up with search results and intermediate logs, and the instructions that mattered at the start get pushed further and further back. A subagent sends that side work to a different room entirely, a separate context, and hands back only the result.

You've probably run into this before: ask Claude Code to research something and draft it in the same conversation, and the answers get noticeably worse toward the end.

Last lesson turned a repeated procedure into a single skill. Today's about splitting the work up further, for when that one skill can't carry the whole job anymore. Just here for how to build a subagent? This lesson alone covers it. The details shift a little with every release, so if you're reading this much later, cross-check with the official docs too.

Subagent

A subagent is a specialized AI worker delegated to handle one specific task. It runs in its own context window, separate from the main conversation, carries its own system prompt and tool permissions, and when it's done, hands back a summarized result instead of the full process. Once a single skill starts trying to research and write at the same time and the results get muddy, it's time to split it into a subagent.

What a subagent actually does

The official docs, in "Creating custom subagents," describe subagents in exactly these three terms: each runs in its own context window, carries a custom system prompt and specific tool access, and operates with independent permissions. Delegate the side work whenever it would fill the main conversation with search results, logs, or file contents you won't reference again, and all of that piles up inside the subagent instead, while only the conclusion comes back to the main conversation.

Claude Code actually ships with a handful of subagents built in already. Explore, tuned for searching a codebase; Plan, which handles research in plan mode; and general-purpose, for complex work that needs both exploring and editing. If you've followed this track and watched Claude Code dig through files to find an answer, odds are one of these built-in subagents was already running behind the scenes.

There's one command that trips people up because the name looks so similar. Type claude agents --help in your terminal and you get an entirely different feature: "Manage background agents." That isn't the subagent this lesson covers. It manages background sessions: close the terminal window and they keep running, because a separate local supervisor process holds onto them. But if your computer falls asleep, the session pauses right along with it, and resumes when your computer wakes up. Running while your computer is completely powered off belongs to a different automation, the cloud routines from the next lesson. Keep the two straight. Subagent files, meanwhile, live strictly in .claude/agents/, and the official docs are explicit here too: despite the similar name, this is a separate feature. One more note: as of v2.1.198, typing /agents no longer opens the interactive wizard it used to. It just prints a message telling you to ask Claude directly or edit .claude/agents/ yourself instead. Check your version with claude --version; if it's newer than that, this is the behavior you'll see. Worth confirming once in your own setup.

Subagent files are markdown with YAML frontmatter, same as skills. Here are the fields you'll actually use:

Location follows the same logic as skills too. Keep it project-only in .claude/agents/, or make it available across every project in ~/.claude/agents/. There are two ways to restrict tools. List an allowlist under tools and anything not on that list is off-limits; list an exclusion under disallowedTools instead, and everything else still gets inherited from the main conversation. For a subagent that should only read and never touch anything, narrow it down with tools. For most others, where you just want to block one specific tool, disallowedTools is less to maintain.

Building one and delegating to it

Let's build one against this track's running scenario, the monthly client content report. Last lesson's monthly-report-draft skill handled everything in one pass, from gathering material to writing the table. This time, split off just the material-gathering step into its own dedicated subagent.

Create .claude/agents/report-researcher.md:

---
name: report-researcher
description: Gathers this month's client content posts and per-channel metrics and returns a summary. Use it when the research step would otherwise fill the conversation with search results and logs.
tools: Read, Grep, Glob, WebFetch
model: haiku
---
 
You are a dedicated research assistant. Find this month's and last month's post
lists and per-channel metrics and organize them into a table. Don't include the
file paths you checked or your intermediate search steps in the result, just
return the finished table with a one-line summary.

There's a reason for model: haiku here. Gathering material and organizing it into a table doesn't call for complex judgment, so routing it to a faster, cheaper model, exactly what the official docs recommend, doesn't meaningfully change the outcome. tools is narrowed to the read-and-search family only, so this subagent has no way to accidentally edit a file.

Save it, then ask something like "gather this month's material with the report-researcher subagent," and Claude decides whether to delegate. The subagent scans files and material in its own separate context and hands back only a table and a summary to the main conversation. Only after that result comes back do you pass it to last lesson's monthly-report-draft skill to actually write the draft. While it's running, the main conversation just shows a delegation indicator (labeled "Backgrounded agent" when it's running in the background, as seen on the August 2026 UI) plus an agent list underneath, with no visibility into which files it checked or how many. That's not being hidden from you, it's that the information never crosses into the main conversation's context in the first place.

All that comes back to the main conversation is this tidy set of tables and a summary. How many times the subagent read the CSVs never lands here.

How is this different from a skill

Lesson 1 flagged the English autocomplete query "subagents vs skills" as a sign these five tools get confused with each other. Time to untangle it properly. One sentence: a skill is a written procedure for what to do and how; a subagent is a worker that actually takes that procedure, including it, and carries out the work.

The two overlap too. Add a skills field to a subagent's frontmatter, and that subagent starts up having already read the content of a specific skill. Say report-researcher needs to reference the same table format every time; write skills: [monthly-report-draft] and it has that procedure in hand from the start. If a skill is the document describing how to do the work, a subagent is the person who takes that document, actually leaves the room, and comes back having done it.

When not to use a subagent: short or interactive tasks

The official docs narrow the case for using a subagent down to one condition: when the side work would fill the main conversation with search results, logs, or file contents you won't reference again. Read that backward and you get the cases where you shouldn't.

Attaching a subagent to a quick check is actually a net loss. Opening a new context, finishing the task, and summarizing the result back is itself time spent on the round trip. If all you need is to open one file and check one value, doing it yourself is faster. Information you'll need to keep referencing shouldn't go to a subagent either. All a subagent hands back is a summarized result, so if you'll need to look back at the file contents it skimmed through partway, don't split the context off in the first place. The same goes for anything where you need to watch the results live and adjust your next instruction on the fly. Once you delegate to a subagent, it's hard to step in until the result comes back.

Boil it down to one question: will you need to look back at the intermediate process once this is done, or is a summarized result enough? If the latter, splitting it off to a subagent is fine. If the former, don't split it off in the first place. What report-researcher hands back, a table, is by itself everything the draft needs, so it falls into the latter case. But if the job had required checking, file by file, exactly where each number came from, it wouldn't have gone to a subagent at all.

There's parallel work bigger than a subagent in the official docs too: agent views, for scattering multiple sessions and checking back later; agent teams, where multiple agents collaborate; and dynamic workflows, for orchestrating large jobs by script. These lean toward large-scale orchestration and developer territory, though, so this track doesn't cover them. At this stage, cleanly splitting off one piece of side work is all you need.

The moment a subagent starts to feel necessary arrives differently for different people. Some get there because sitting idle while one skill runs starts to feel like wasted time. Some get there because research results fill up the conversation and crowd out the context for the work they actually meant to do. Some get there because the skills built up in an earlier lesson multiplied until coordinating the order between them got unwieldy. For me it was the first one. Running skills one after another kept generating dead time waiting, so I moved to delegating data-gathering and research to an agent that only does that, and kept a separate writing agent and a separate fact-checking agent. Whichever route gets you here, you land in the same place. Split off the side work, and the main conversation gets lighter while the waiting starts overlapping instead of stacking up.