Claude Code Subagents Explained

Claude Code subagents are one of the most useful features for anyone running larger tasks with Anthropic's agentic coding tool. A subagent is a specialized agent — with its own context window, its own set of allowed tools, and its own system prompt — that the main agent can delegate work to. Instead of cramming every search result, file read, and review pass into a single conversation, the primary agent hands a focused job to a subagent, gets back a clean summary, and keeps its own context tidy. This guide explains what subagents are, why they help, and how they fit alongside the rest of Claude Code's building blocks. (Claude Drops is an independent app and is not affiliated with Anthropic; for exact syntax always check the official Claude Code docs.)

What are Claude Code subagents?

At its core, a Claude Code subagent is a separate agent instance that the main agent invokes to handle a specific, well-scoped piece of work. Think of the primary agent as a lead engineer and subagents as teammates it can assign tasks to. Each subagent runs with three things that make it distinct: a dedicated context window, a tool allowlist, and a custom system prompt describing its role and how it should behave.

When the main agent delegates, the subagent does its work in isolation and returns a concise result — not the full transcript of everything it read or ran. That single design choice is what makes subagents so valuable on real codebases, and it shows up across many of the Claude Code changelog entries that have refined agent behavior over time.

Claude Code also ships with a few built-in subagents that it uses automatically when a task fits, such as a fast read-only Explore agent for searching code, a Plan agent that gathers context during plan mode, and a general-purpose agent for multi-step work. Custom subagents simply let you define your own roles on top of these.

Why Claude Code subagents matter: three real benefits

Subagents solve problems that come up constantly when you point an agent at a non-trivial repository. There are three benefits worth understanding before you start using them.

Context isolation

The biggest win is keeping the main agent's context clean. Exploring a large codebase to answer a single question can pull in thousands of lines of files, test output, and grep hits. If all of that lands in the primary conversation, it crowds out the actual task and degrades the agent's focus. By sending the exploration to a subagent, only the answer comes back — the noisy intermediate steps stay in the subagent's own window. This is the same motivation behind context management features tracked in the changelog.

Parallelism

Because subagents are independent, the main agent can run several at once. This is where the term claude code parallel agents comes from: instead of investigating three modules one after another, the primary agent can fan out three subagents, let them work concurrently, and then merge their findings. Subagents can run in the foreground (blocking until done) or in the background (concurrently, while you keep working). For research-heavy or multi-part tasks, this can meaningfully cut wall-clock time.

Specialization and cost control

A subagent's system prompt lets you bake in a focused role. A code-reviewer subagent can be told exactly what to look for and which standards to enforce. An explore/search subagent can be tuned to return file paths and summaries rather than dumping whole files. Pairing a tight prompt with a narrow tool allowlist — read-only tools for a reviewer, for instance — produces more predictable output than asking one general-purpose agent to do everything. You can also route lighter work to a faster, cheaper model to keep costs down.

Common subagent patterns

A few archetypes show up again and again in practice. You do not need all of them, but they illustrate how teams structure delegation.

• Explore / search agent — given a question, it greps and reads across the repo and returns a concise map of where the relevant code lives, without flooding the main context. Claude Code's built-in Explore agent fills this role by default.
• Code reviewer — invoked after changes, it inspects a diff against your conventions and reports issues. Often restricted to read-only tools so it can analyze but not edit.
• Test runner / debugger — runs the suite, parses failures, and summarizes what broke rather than returning raw, verbose logs.
• Domain specialist — a subagent prompted with deep knowledge of one area (a payments module, a design system, a data pipeline) so its advice stays on-target.

How Claude Code subagents are defined

Custom subagents are Markdown files with YAML frontmatter. Project-level subagents live in a .claude/agents/ directory inside your repository, so the whole team can share them; user-level subagents live in ~/.claude/agents/ and follow you across projects. Each file describes the agent's name, the description that tells the main agent when to delegate to it, an optional restricted tool set, an optional model, and a system prompt (the Markdown body) that shapes its behavior. The built-in /agents command gives you a guided interface to create, edit, and manage them.

Conceptually a definition looks like the sketch below. Treat this as illustrative — for the complete, current list of frontmatter fields and any flags, defer to the Claude Code docs, since these details evolve between releases.

# .claude/agents/code-reviewer.md (illustrative)
---
name: code-reviewer
description: Reviews diffs for bugs and style. Use after changes are made.
tools: Read, Grep, Glob   # read-only, scoped down
model: sonnet
---

You are a meticulous code reviewer. Inspect the changes against the
project's conventions. Report correctness bugs first, then style.
Be specific and cite file paths and line numbers.

The description matters more than it looks: the main agent reads it to decide which subagent fits a task. A vague description leads to a subagent that never gets used (or gets used at the wrong time), so write it like a job posting — clear about what the agent is for and when to call it.

Subagents vs. skills vs. the main agent

It is easy to confuse subagents with related features. The short version: a subagent is a who (a separate agent with its own context and tools), while a skill is a how (packaged instructions and resources the agent loads on demand). They compose well — a subagent can itself use skills. For a deeper look at the latter, see Claude Code skills explained, and for definitions of the surrounding terminology, the Claude Code glossary is a handy reference.

When to use a subagent (and when not to)

Subagents shine when a task is self-contained, generates a lot of intermediate noise, or benefits from a specialized perspective. They are less helpful for quick, single-step edits where the overhead of delegating outweighs the benefit.

• Reach for a subagent when exploring an unfamiliar codebase, running a focused review, or fanning out independent investigations in parallel.
• Skip it for a one-line fix, a rename, or anything where you already have all the context loaded and the round-trip would just add latency.
• Remember that a subagent returns a summary — if you need the main agent to keep every detail, delegation may hide information you actually wanted.

Getting started

The lowest-friction way to begin is to run /agents and let Claude Code help you author a subagent, then review the file it produces in .claude/agents/. Start with a clear role, a tight description, and the minimum tools the agent needs. Commit project-level subagents so your whole team benefits, and iterate on the system prompt as you see how the main agent delegates in practice.

Subagents are a steadily evolving part of Claude Code, so it is worth watching how the behavior changes release to release. You can follow new updates on the Claude Code changelog — or get push notifications the moment a new version ships by grabbing the app. As always, the official docs are the source of truth for exact configuration syntax.