Creating a subagent

You've just finished a feature branch and you want Claude Code to review it — but not in the same thread that wrote it. You want a reviewer with its own context, its own instructions, and a narrow set of tools. That's a custom subagent, and it takes about two minutes to create one.

This lesson walks through the full flow. We'll build a code-quality-reviewer from scratch and look at the config file Claude Code writes for you, field by field.

The /agents command

/agents is the main interface for managing subagents in Claude Code. Run it from anywhere in a session and you'll land on a panel listing your current subagents with options to create, edit, or delete them. Select Create new agent to start.

Step 1 — Pick a scope

Claude Code asks where the subagent should live:

• Project-level — available only in the current project. Lives at .claude/agents/ inside the repo and can be committed so the whole team shares it.
• User-level — shared across every project on your machine. Useful for generic helpers you always want around.

For a reviewer that encodes project-specific standards, pick project-level. For a general research assistant you want everywhere, pick user-level.

Step 2 — Let Claude generate it

You can write the configuration by hand, but the faster path is to describe what you want and let Claude generate the name, description, and system prompt for you. For our reviewer, something like:

Make a subagent that reviews code quality and security issues in recently modified files.

Claude produces a first draft of the whole config from that one sentence. You'll refine it shortly — the auto-generated version is a starting point, not the final word.

Step 3 — Customize the tools

Next comes tool access. Claude Code groups tools into five categories:

• Read-only — Glob, Grep, Read, WebFetch, WebSearch
• Edit — Edit, Write, MultiEdit
• Execution — Bash
• MCP — tools from connected MCP servers
• Other — everything else

Match the tools to the role. A code reviewer should read and analyze code, not change it — so turn Edit off. Execution stays on, because git diff and friends make it much easier for the reviewer to identify pending changes. (That's a deliberate call: you could turn it off for a stricter reviewer, but leaving it on trades a little power for a lot of usefulness.)

The rule of thumb: give a subagent exactly the tools its job requires, and nothing more.

Step 4 — Choose a model

You select which Claude model powers the subagent:

• Haiku — fast and lightweight. Good for quick, mechanical tasks.
• Sonnet — a middle ground between speed and depth. Sensible default for most subagents.
• Opus — best for complex analysis and reasoning-heavy work.
• Inherit — uses whatever model your main conversation is running.

For a code reviewer, Sonnet is usually the right call. Opus if the reviewer is doing serious architectural analysis; Haiku if it's running a mechanical style pass.

Step 5 — Pick a color

Finally, a color. This shows up in the UI when the subagent is active, so you can tell at a glance which one is running. Small touch, but it matters when you have several subagents and want to see who's doing what.

The config file

Once creation is complete, the subagent is saved as a markdown file — typically at .claude/agents/code-quality-reviewer.md. Open it and you'll see something like this:

---
name: code-quality-reviewer
description: Use this agent when you need to review recently written or modified code for quality, security, and best practice compliance.
tools: Bash, Glob, Grep, Read, WebFetch, WebSearch
model: sonnet
color: purple
---

You are an expert code reviewer specializing in quality assurance, security best practices, and
adherence to project standards. Your role is to thoroughly examine recently written or modified code
and identify issues that could impact reliability, security, maintainability, or performance.

Two parts: a YAML frontmatter block, and a markdown body. Let's go through each field.

YAML frontmatter

• name — a unique identifier. This is how you reference the subagent, either by asking Claude directly ("run the code quality reviewer") or explicitly with @agent code-quality-reviewer in your message.
• description — controls when Claude decides to use the subagent. This must be a single line; if you need line breaks, use escaped \n characters. The description is read by the main agent to decide whether to delegate and how to frame the task.
• tools — the list of tools the subagent can access. Matches whatever you selected during creation, but you can edit this list directly in the file at any time.
• model — which model powers the subagent. One of haiku, sonnet, opus, or inherit.
• color — the UI color for identifying the subagent while it's running.

The system prompt body

Everything below the frontmatter is the system prompt. This is where you tell the subagent what to focus on, how to analyze its subject, and how to structure its findings when it reports back. A well-written system prompt is the difference between a reviewer that produces a scattered list of "maybe issues" and one that delivers a clean, structured report every time.

We'll cover the patterns that make system prompts effective in the next lesson. For now, know that the body is the lever you'll use most when refining a subagent.

Making Claude delegate automatically

By default, Claude uses a subagent when it decides the task matches. You can push harder on that in two ways.

Add "proactively" to the description. Including the word proactively in the description field signals to Claude that it should auto-delegate to this subagent whenever it looks relevant — not just when you explicitly ask. For example:

Proactively suggest running this agent after major code changes...

Add example conversations to the description. Concrete examples of when the subagent should be used help Claude learn the trigger scenarios. The more specific, the better.

If your subagent isn't being used when you expect it to, the description is almost always the place to look. Make it more specific. Add examples. The name and description are what Claude sees when deciding whether to delegate — tune them until delegation becomes reliable.

Testing it

The last step is the fun one. Make some changes in your repo, then ask Claude to review them. If the subagent fires, you'll see its color in the UI and a focused review in your main thread. If it doesn't, go back to the description and add a trigger scenario that matches what you just tried.