Claude CodeBeginner

How to Create Your First Subagent in Claude Code

Build a reusable, specialized subagent with its own prompt and tool access using the /agents command.

8 minBeginner

A subagent is a specialized assistant that Claude Code can delegate work to. Each subagent has its own system prompt, its own restricted set of tools, and runs in a separate context window, so it does not clutter your main conversation. This guide creates a focused code-reviewer subagent and shows how it gets invoked.

Claude Code installed and a project open
A clear single job for the subagent to specialize in
Five minutes to write a short, sharp prompt

Step 1: Open the agents manager

Inside a session, run the agents command. It opens an interactive manager where you can create new subagents, choose whether they live in the project or your user folder, and pick which tools they may use.

claude - my-project

$/agents

Manage subagents

Choose: Create new agent

Step 2: Understand the file it creates

A subagent is just a Markdown file with YAML frontmatter. Project subagents live in .claude/agents, user subagents in ~/.claude/agents. The frontmatter holds the name, a description that tells Claude when to delegate, and an optional tools list. The body is the system prompt.

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews recently changed code for bugs and clarity. Use proactively after edits.
tools: Read, Grep, Glob, Bash
---

You are a focused code reviewer. When invoked:

1. Run git diff to see what changed.
2. Read the changed files in full for context.
3. Report only real issues, ordered by severity.
4. For each issue give the file, the line, and a concrete fix.

Do not rewrite unrelated code. Be terse.

.claude/agents/code-reviewer.md

Explorer

agents

code-reviewer.md

settings.json

.claude/agents/code-reviewer.md

1---

2name: code-reviewer

3description: Reviews changed code...

4tools: Read, Grep, Glob, Bash

5---

7You are a focused code reviewer...

Subagents are plain Markdown files you can commit with the repo.

Write the description for the dispatcher

The description field is how the main agent decides when to hand off. Phrases like "use proactively" or "use immediately after" make automatic delegation more reliable than a vague one-liner.

Step 3: Invoke it

You can let Claude delegate automatically based on the description, or call the subagent explicitly by name. Explicit invocation is handy while you are testing the prompt.

Claude Code

You

Use the code-reviewer subagent on my last commit.

Agent

Delegating to code-reviewer... Done. 2 issues found: unhandled null in parse.ts:41, and a duplicated fetch in api.ts:88. Want the fixes applied?

Step 4: Iterate on the prompt

Open the Markdown file and tighten the instructions whenever the subagent drifts. Because it is version-controlled text, you can review changes in pull requests like any other code.

Example: a code-reviewer subagent that only reads, greps, and runs git, so it can never accidentally edit files while it reviews. The main agent stays clean while the review runs in its own context.