Claude Code subagents are specialized AI assistants you delegate specific tasks to. Each runs in its own context window with its own system prompt and allowed tools, works independently, and returns only the result to your main conversation. They're especially useful for isolating verbose side work — running tests, fetching docs — so your main session stays clean. (As of June 2026 · Official: code.claude.com/sub-agents)
What a subagent is
Per the official docs, subagents are AI assistants pre-configured to handle specific kinds of tasks. Each has its own purpose and expertise, runs in a context window separate from the main conversation, and is shaped by its allowed tools and custom system prompt. When Claude Code judges that a task matches a subagent's description, it delegates that task; the subagent works independently and returns results.
Why use them
- Context preservation — verbose side output (test logs, docs, file contents) stays inside the subagent, and only a summary returns to the main conversation.
- Specialized expertise — tuned with detailed domain instructions, raising success rates on that task.
- Reusability — once created, usable across projects and shareable with your team.
- Flexible permissions — each subagent can have different tool access, limiting powerful tools to specific agents.
Creating one
The easiest way is the /agents command. Run it, choose project/user level under "Create New Agent," and define the description and allowed tools (generating a draft with Claude then customizing is recommended). You can also create one as a markdown file directly. A subagent is, in the end, a single markdown file: the YAML frontmatter at the top (name, description, tools) is the config, and the body becomes the agent's system prompt.
Where they live
- Project subagents —
.claude/agents/. A good fit for workflows that depend on a codebase's conventions; shared with the team via git. - User subagents —
~/.claude/agents/. A good fit for portable habits like repo exploration or docs lookup.
Note that subagents do not inherit the full default Claude Code system prompt. They get their own prompt plus basic environment details, which actually makes them easier to shape deliberately.
How delegation works
Claude uses each subagent's description as a routing hint to decide whether to delegate. So a good subagent is more than a persona — it's a clearly scoped, recurring job with the right tools and instructions and a clear "when to use this." The clearer the description, the more reliably the right work is delegated automatically.
Things to know
- One level deep — a subagent can't spawn another subagent. Keep orchestration (invoking specialists, merging results) in the main session.
- Parallel — you can run independent work across multiple subagents at once.
- Built-ins — even without custom ones, general-purpose helpers are included (the exact list varies by version).
- Tokens — subagents also consume tokens in their own context. Used well they keep the main session light; overused they burn budget.
Related
- Slash commands — managed via
/agents - Claude Code Skills — compare ways to extend
- How-to-use guide — using it in the terminal
- CLAUDE.md guide — persistent project context
Disclaimer: This article is based on Anthropic's official Claude Code docs (code.claude.com·docs.anthropic.com). Built-in subagent lists, environment variables, and detailed behavior may change by policy and version. Commands, paths, and frontmatter fields may also change over time — check the official docs for the latest. This site is not affiliated with Anthropic.