When you create a subagent in Claude Code, you spin up a specialized Claude instance with its own context window, custom system prompt, and specific tool access — ideal for focused tasks like code review, testing, or research that might otherwise clutter your main conversation.

Steps to Create a Subagent in Claude Code

Option A — Ask Claude to write it for you (recommended)

1. In a Claude Code session, describe the subagent you want, e.g.:
   “Create a personal code-improver subagent in ~/.claude/agents/ that scans files and suggests improvements for readability, performance, and best practices. Make it read-only and have it use Sonnet.”
2. Claude will generate the Markdown file with the right frontmatter (name, description, tools, model) and system prompt.
3. Open the file it created and tweak anything you’d like.

Note: as of Claude Code v2.1.198+, the old /agents interactive wizard was removed. Running /agents now just reminds you to ask Claude directly or edit the files yourself — but the file format and locations are unchanged.

Option B — Write the file manually

1. Create a Markdown file in one of these locations:
   • .claude/agents/your-agent-name.md → project-level (shared with your team via the repo)
   • ~/.claude/agents/your-agent-name.md → personal, available across all your projects
2. Add YAML frontmatter + a system prompt body. Example:

markdown

---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after code changes to check security, style, and maintainability.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You are a senior code reviewer. When invoked:
1. Run `git diff` to identify modified files.
2. Focus review on changed code paths.
3. List security issues, likely false positives, and suggested fixes.
4. Provide a short, prioritized action list.

3. Restart your Claude Code session — subagent files are loaded only at startup, so edits on disk won’t take effect until you restart. (Agents created via asking Claude in a live session take effect immediately.)

Key Frontmatter Fields for Subagents

Using Your Claude Code Subagent

• Let Claude auto-delegate based on the description matching your request, or
• Invoke explicitly: claude -p "Use the code-reviewer subagent to review payment.py"

Claude Code also ships with built-in subagents (Explore, Plan, general-purpose) that it uses automatically without you needing to configure anything.

Conclusion: Using Claude Code Subagents

Subagents are one of the most practical upgrades you can make to your Claude Code workflow. By delegating token-heavy, repetitive, or specialized tasks — like code review, testing, or codebase exploration — to a dedicated subagent, you keep your main conversation focused and your context window clean.

Getting started is simple: describe what you want to Claude and let it generate the subagent for you, or hand-write a Markdown file with the right YAML frontmatter in .claude/agents/ or ~/.claude/agents/. From there, it’s just a matter of refining the description field so Claude knows exactly when to delegate, and restricting tools and model choices to match the task at hand. For deeper dives into implementation patterns, check out our e-books.

Frequently Asked Questions About Claude Code Subagents

What is a subagent in Claude Code?

A subagent is a specialized Claude instance you configure with its own system prompt, tool access, and optional model choice. It runs in a separate context window, letting you delegate focused tasks — like code review, testing, or research — without cluttering your main conversation.

Where are subagent files stored?

Subagent definition files are Markdown files stored in one of two locations: .claude/agents/ inside your project directory (shared with your team via the repository) or ~/.claude/agents/ in your home directory (personal agents available across all projects).

How do you invoke a subagent explicitly?

You can invoke a specific agent by name using the -p flag: claude -p "Use the code-reviewer subagent to review payment.py". Alternatively, Claude will auto-delegate to the right agent based on your request matching the agent’s description field — no explicit invocation needed.

Can subagents use tools?

Yes. You define which tools a subagent can access using the tools frontmatter field. For example, a read-only reviewer might be limited to Read, Grep, Glob, while a more capable agent could also include Bash or Write. Restricting tools is a good way to enforce safe, predictable behavior.

How to Create a Subagent in Claude Code

1. Choose a focused task. Pick one repetitive or specialized workflow — such as code review, test generation, or documentation — that benefits from a dedicated context and toolset.
2. Create the Markdown file. Add a .md file to .claude/agents/ (project-level, shared with your team) or ~/.claude/agents/ (personal, available across all projects). Use a clear, hyphenated filename like code-reviewer.md.
3. Add YAML frontmatter and a system prompt. At the top of the file, include name, description (written as a clear trigger condition), tools, and optionally model. Below the frontmatter delimiter (---), write the agent’s instructions in plain language.
4. Restart or reload Claude Code. Agents defined in files are loaded at session startup, so restart your session for the new agent to become available. Agents created by asking Claude directly take effect immediately without a restart.
5. Test and refine. Ask Claude to use the agent or trigger it automatically via its description. If the behavior isn’t quite right, adjust the system prompt, tighten the description trigger, or change the allowed tools, then restart and test again.

Start small — one or two subagents for your most repetitive tasks — and expand as you find more workflows worth isolating. Once you experience how much cleaner and faster your sessions become, it’s hard to go back to a single generalist agent handling everything. Learn more about advanced Claude Code techniques.