How to Build Your First Subagent in Claude Code

If you keep asking Claude Code to do the same specialized job again and again, a subagent is the right tool. Subagents give Claude a reusable specialist with its own prompt, tool access, and separate context window.

This guide shows the shortest path to a useful first subagent.

What a Subagent Is

Anthropic describes subagents as specialized AI assistants that Claude Code can delegate to for specific kinds of work. Each subagent:

• has a clear purpose
• uses its own context window
• can have its own tool access
• is defined by a small Markdown file with YAML frontmatter

This is useful when you want Claude to stop behaving like a generalist and start behaving like a reliable reviewer, debugger, migration checker, or release helper.

When to Create One

A subagent is worth creating when all three are true:

• the task comes up repeatedly
• the task benefits from a consistent checklist
• you want Claude to keep the main conversation cleaner

Good first subagents:

• code reviewer
• test failure investigator
• migration checker
• security reviewer
• docs updater

Fastest Way: Use /agents

The easiest setup path is the built-in UI:

/agents

Then:

1. choose "Create New subagent"
2. give it a short lowercase name
3. write a description that says when Claude should use it
4. decide which tools it needs
5. save it

That is the best option for your first subagent because Claude Code shows the available tools and reduces format mistakes.

File-Based Setup in .claude/agents

If you prefer to manage subagents in version control, create a file in:

.claude/agents/

Anthropic documents two scopes:

• project subagents: .claude/agents/
• user subagents: ~/.claude/agents/

Project subagents win if names conflict.

A Good First Example

Create .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Review code changes for correctness, regression risk, and obvious security problems when asked to review a diff, module, or pull request.
tools: Read, Grep, Glob, Bash
---

You are a focused code review subagent.

Priorities:
- Find bugs before style issues
- Call out regression risk clearly
- Prefer concrete evidence from files or diffs
- Keep feedback short and specific

When reviewing changes:
1. Understand the intent of the change
2. Check for logic mistakes and missing edge cases
3. Check for unsafe assumptions and security issues
4. Flag missing tests when coverage looks weak
5. Return findings in priority order

This is enough to be useful. You do not need a giant system prompt.

How to Invoke It

You have two ways to use a subagent.

Let Claude pick it automatically

If your description is clear, Claude Code can delegate on its own.

Examples:

review my recent auth changes for regression risk
run all tests and investigate the failures

Ask for it explicitly

You can also tell Claude which subagent to use:

use the code-reviewer subagent to inspect the auth module
use the code-reviewer subagent on my current git diff

Tool Access: Start Narrow

Anthropic recommends limiting tool access to what the subagent actually needs.

Practical rule:

• use Read, Grep, and Glob for read-heavy reviewers
• add Bash only if the agent genuinely needs commands
• omit tools only if you intentionally want it to inherit everything

Your first subagent should usually be read-focused, not edit-focused.

Common Mistakes

1. Vague descriptions

Bad:

• "helps with code"

Better:

• "reviews schema migrations for rollback risk and missing indexes"

The description is what helps Claude decide when to delegate.

2. Too many tools

If you give every subagent full tool access, you lose most of the safety and clarity benefits. Keep the permissions as small as possible.

3. Writing a giant prompt

Your first prompt should be a compact checklist, not a manifesto. If the subagent needs six screens of explanation, the task is probably still too broad.

4. Creating a subagent for a one-off task

If you only need it once, just write a normal prompt. Subagents pay off when the workflow repeats.

A Good First Workflow

If you want a low-risk first win, do this:

1. create a code-reviewer subagent
2. keep it read-only or nearly read-only
3. run it on your current diff
4. adjust the description after two or three real uses

That usually gives you a useful specialist in under 10 minutes.

Quick Checklist

• Start with /agents
• Give the subagent one clear job
• Write a concrete description
• Limit tool access
• Keep the prompt short
• Test it on a real task
• Refine the description after repeated use

Official References

• Subagents
• Common workflows