How to Use Subagents in Claude Code

Subagents let you split work in Claude Code across specialized helpers instead of running everything in one conversation. Each subagent has its own context window, its own instructions and its own limited set of tools, so it can focus on one job and hand back a clean result. Here is how they work and how to make your own. If you are new to the tool, start with how to install Claude Code.

What subagents are

A subagent is a specialized assistant that Claude Code can delegate a task to. Each one runs with:

• Its own context window, separate from your main conversation, so verbose output like logs and file contents does not clutter your session.
• A custom system prompt that defines its role and how it should behave.
• A specific set of tools, which you can restrict for focus or safety.

Because the work happens in isolation and only a summary comes back, subagents are useful for keeping your main context clean, enforcing constraints (for example a read-only research helper), and reusing the same setup across projects.

Creating a subagent

The quickest way is the /agents command, which opens an interactive menu for creating and managing subagents. You can also just ask Claude in plain language to create one for you.

Under the hood, every subagent is a Markdown file with a YAML frontmatter block. Two fields are required, name and description, and the rest are optional. Here is a working code-reviewer example you could save as .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security and maintainability. 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

Review checklist:
- Code is clear and readable
- Functions and variables are well named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented

Provide feedback organized by priority: critical issues, warnings and suggestions.
Include specific examples of how to fix issues.

A few things to know about the frontmatter:

• name is a unique, lowercase, hyphenated identifier.
• description tells Claude when to delegate to this subagent, so write it clearly.
• tools is an optional allowlist. If you leave it out, the subagent inherits the available tools. Listing only what it needs keeps it focused.
• model is optional and can be sonnet, opus, haiku, inherit or a full model ID. Routing a simple task to a smaller model can save cost.

Everything below the frontmatter is the system prompt that shapes how the subagent behaves.

Project versus personal subagents

Where you save the file decides who can use it:

• Project subagents live in .claude/agents/ inside your repository. Check them into version control so your whole team shares the same helpers.
• Personal subagents live in ~/.claude/agents/ and are available across every project on your machine.

If a project subagent and a personal one share the same name, the project version wins, so teams can standardize behavior without stepping on individual setups.

Delegating to a subagent

Claude Code can use a subagent two ways. It delegates automatically when a task matches a subagent’s description, which is why a clear description matters. You can also invoke one explicitly, for example by asking Claude to “use the code-reviewer subagent on my recent changes.” Naming it directly guarantees that subagent runs. You can even set a session to run under a specific subagent from the start.

Reach for a subagent when the task is self-contained, produces a lot of output, or needs tighter tool restrictions. Stay in the main conversation when you need frequent back-and-forth or the work shares a lot of context. To automate what happens around these runs, look at Claude Code hooks, and to give every session shared context, see memory and CLAUDE.md.

Keep going

Subagents are one of the ways Claude Code scales from single prompts to real workflows. Browse the rest of the Claude Code hub for guides like slash commands and more. To build the broader AI skills behind tools like this, our AI course covers working with AI day to day, and you can start with the free lessons first.