Create Your First Claude Code Subagent

A subagent is a specialized assistant that Claude Code can hand a side task to. It runs in its own separate context window, with its own system prompt and its own set of tools, then returns only a summary of what it found.

That isolation is the whole point. When Claude delegates work to a subagent, the verbose stuff — search results, logs, file contents you'll never reference again — stays inside the subagent's context instead of flooding your main conversation. Your main session stays focused and uncluttered.

Reach for a subagent when a task is self-contained and you only care about the result, not the noisy process of getting there. According to the official docs, subagents help you:

• Preserve context — keep exploration and high-volume output out of your main conversation.
• Enforce constraints — limit which tools a subagent can use (for example, a read-only reviewer with no Write or Edit).
• Reuse configurations — define a worker once and use it across projects.
• Specialize behavior — give it a focused system prompt for one domain.

A good rule of thumb: stay in the main conversation for quick, iterative changes that need back-and-forth. Use a subagent when the work produces verbose output you don't need to keep, or when you want specific tool restrictions.

The recommended way to create and manage subagents is the /agents command. Inside a Claude Code session, run:

/agents

This opens a tabbed interface. Switch to the Library tab, choose Create new agent, then pick a scope:

• Personal saves it to ~/.claude/agents/, so it's available in all your projects.
• Project saves it to .claude/agents/ in the current repo, so you can check it into version control and share it with your team.

Claude can then generate the identifier, description, and system prompt for you from a plain-language description, after which you select the tools and model the subagent should use. Save it and the subagent is available immediately.

Under the hood, every subagent is just a Markdown file with YAML frontmatter. Only name and description are required; the body becomes the subagent's system prompt. Here's the official code-reviewer example — a read-only reviewer that can't modify your files:

---
name: code-reviewer
description: Expert code review specialist. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of
code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

A few things worth knowing:

• tools is optional — omit it and the subagent inherits every tool from the main conversation. Listing tools (as above) restricts it to just those.
• model defaults to inherit (same model as your session). You can also set sonnet, opus, or haiku.
• The description is how Claude decides when to delegate. Adding "use proactively" encourages it to reach for the subagent on its own.

Once a subagent exists, Claude often delegates to it automatically based on its description. You can also call it explicitly — just name it in plain language:

Use the code-reviewer subagent to look at my recent changes

To guarantee a specific subagent runs, @-mention it (type @ and pick it from the list, the same way you @-mention files). Claude delegates, the subagent does its work in isolation, and only its summary returns to you.