Claude Code Subagents: How to Create and Use Them (2026)

Maya was three hours into a payments refactor when she asked Claude Code to "quickly check why the staging logs look weird." Forty messages later, her main conversation was buried under log dumps and two dead-end theories, and the refactor she cared about had scrolled off the top. The side-quest had eaten her context. Claude Code subagents exist for exactly that moment: hand the log investigation to a separate assistant with its own context window, get back a three-line answer, and keep your main thread clean. This guide covers what a subagent is, how to build one in .claude/agents/*.md, when the isolation pays off, and where subagents fall short.

If you have searched both "claude code subagents" and "claude code agents" and wondered whether those are two features, you are in the right place. They are one feature, and we clear up that naming below before getting practical.

What a Subagent Is

A subagent is a specialized assistant defined in a markdown file under .claude/agents/. It has its own system prompt, its own isolated context window, and an optional list of tools it is allowed to touch. Claude Code delegates a focused task to it, the subagent does the work in its own context, and only the final result returns to your main conversation. Everything it read, tried, and discarded along the way stays in its window, not yours.

That isolation is the entire reason subagents exist. Your main session has a finite context budget, and a messy side-task spends it fast. A subagent gives the side-task a sandbox. A test-writer subagent can read ten files, draft three failing tests, and report back "added 4 tests, all green" without ever showing you the ten files it skimmed.

Subagents are not the only way to extend Claude Code. Skills give the agent reusable instructions, MCP servers give it new tools, and hooks make it run shell commands on events. Subagents are the one that adds a fresh context window. Keep that single difference in your head and the rest of this clicks into place. (New to the setup? The skill registry is a fast way to see working examples; browse it when you have a minute.)

Creating Your First Subagent

A subagent is a plain markdown file with YAML frontmatter on top and a system prompt in the body. Drop it in .claude/agents/ for a single project, or ~/.claude/agents/ to make it available everywhere. Here is a complete code-reviewer subagent:

---
name: code-reviewer
description: Reviews staged changes for bugs and style issues. Use after writing or editing code.
tools: Read, Grep, Glob, Bash
---

You are a focused code reviewer. When invoked:
1. Run `git diff --staged` to see the changes.
2. Flag real bugs, unsafe patterns, and missing error handling.
3. Skip nitpicks. Report findings as a short, ranked list.
Be specific: cite file and line, not vague advice.

Three frontmatter fields do the work. name is the identifier Claude Code uses to call the subagent. description tells Claude Code when to reach for it automatically; write it as a trigger ("Use after writing code"), because the main agent reads it to decide when to delegate. tools is optional: list only what the subagent needs, and it inherits nothing else. Omit it and the subagent gets the full tool set.

You do not have to write the file by hand. Run /agents inside Claude Code and it scaffolds the frontmatter, lets you pick allowed tools from a checklist, and saves the file in the right place. Once saved, the subagent is live: Claude Code may invoke it automatically when a task matches the description, or you can call it explicitly ("use the code-reviewer subagent on my staged changes").

When Subagents Earn Their Keep

Subagents pay off in two situations: when a task would pollute your main context, and when you can run several pieces of work at once. Both come down to the isolated context window.

Take the context-pollution case. A reviewer on a fintech team called Larkfield wired up a test-writer subagent in March 2026. Before, asking the main agent to write tests meant it loaded the implementation, the existing test file, and the fixtures: roughly 8,000 tokens of noise that stuck around for the rest of the session. After, the subagent did that reading in its own window and returned "wrote 6 tests in user_auth.test.ts, 6 passing." The main thread stayed on the feature, and the reviewer stopped hitting compaction mid-afternoon.

The second case is parallelism. Because each subagent runs in its own context, Claude Code can dispatch several at once when their tasks do not depend on each other. A research task that would take one agent twenty sequential lookups can be split across four subagents running side by side, each chasing one question, then merged. The win is real only when the subtasks are genuinely independent: fan one out to check four packages for breaking changes, not to write four files that import each other.

If a recurring side-task keeps stealing your main thread, that is the signal to make it a subagent. Several context-isolation and review patterns also ship as installable skills, so you can see what's in the registry rather than build from scratch.

Subagents vs Skills vs MCP

These three get conflated constantly because all of them "extend Claude Code," yet they do different jobs. The quick rule: subagents add a context, skills add instructions, MCP servers add tools.

These combine well. A research subagent can use a skill for its method and an MCP server to query a database, all inside its own context. You are not picking one of the three; you are picking which problem you have right now. If the problem is "this keeps polluting my thread," reach for a subagent.

"Agents" vs "Subagents": The Naming, Cleared Up

"Agents" and "subagents" are the same feature in Claude Code. There is no separate "agents" system you have been missing. The files live in .claude/agents/ and the built-in command is /agents, so in casual use people say agents. The docs say subagents to stress that each one runs underneath your main session, in a context separate from the agent you are typing to.

So when one tutorial says "create a Claude Code agent" and another says "create a subagent," they describe the identical markdown file in the identical folder. The prefix sub- is a relationship, not a different product: your main session is the parent, the spawned helper is the child. Search results split the traffic across both terms, but the answer to "claude code agents" and "claude code subagents" is one and the same.

Subagent Patterns Worth Stealing

You do not need a zoo of subagents. Three patterns cover most of the value, and each maps to a repeated side-task.

• The reviewer:reads the staged diff, flags real bugs, and reports a ranked list. Triggered automatically after edits via its description, it catches the obvious mistakes before you do, and the diff-reading never touches your main context.
• The researcher:fans out across docs, source files, or the web to answer a question, then returns a tight summary with citations. This is the parallel-friendly one: split a "which of these five libraries supports X" question across five subagents.
• The test-writer:reads an implementation, drafts tests against it, runs them, and reports pass or fail counts. All the file-reading and trial-and-error stays sandboxed, so your thread sees "6 tests, all passing," not the scaffolding.

The thread that ties these together: each one owns a task that is noisy, repeatable, and self-contained. That is the profile of a good subagent. If a job is a one-off, or if it needs to stay in lockstep with your main reasoning, it does not want its own context, so leave it in the main thread.

Where Subagents Fall Short

Most write-ups only sell the upside, so here is the counterweight. Subagents are not free, and three things they do badly are worth knowing before you build a dozen of them.

They start cold. A subagent does not see your main conversation. It gets only the task you hand it, so anything it needs to know, you pass in. For tightly coupled work where the context is the point, like debugging a bug that only makes sense given the last twenty messages, delegating to a fresh, amnesiac subagent is slower than staying put.

Round-trips add latency. Spinning up a subagent, briefing it, and collecting its result has overhead. For a five-second task, that overhead is the whole cost. Subagents win on work big or noisy enough that the isolation is worth the handoff, not on quick lookups.

The description is load-bearing. Automatic invocation lives or dies on the description field. Write it vaguely and the main agent either never delegates or delegates to the wrong subagent. A reviewer described as "helps with code" gets ignored; "Use after writing or editing code to catch bugs" gets used. If a subagent never seems to fire, the description is almost always why.

Browse next: How to Add Skills to Claude Code (2026) | Claude Code Hooks (2026) | Claude Code MCP (2026) | Claude Code Commands (2026)

Pick your single most-repeated side-task, the one that keeps hijacking your main thread, and make it a subagent. Live with it for a week. You will know within three uses whether the isolation earns its keep, and a working .claude/agents/*.md file beats a perfect plan you never ship.

Back to Blog