Claude Code Subagents: What They Are and How to Create One

Claude Code subagents are helpers that handle a specific task for your main Claude session. For example, one helper can review a file and return its findings while the main session handles the rest of your request.

In this guide, you will create a code reviewer that can read files but cannot edit them. Then you will give it a small file with a known bug and check its answer.

You do not need an existing app, an MCP server, or a separate Agent SDK project. You need Claude Code, access to an account that can use it, and a text editor.

What is a subagent, in simple terms?

Imagine asking a colleague to review one calculation while you prepare the rest of a report. You give them the relevant page and a clear question. They return their findings.

A subagent serves a similar purpose. It has its own working context: the information it uses while doing its task. This can keep a long investigation from filling the main conversation with every file and search result.

Claude Code has built-in helpers, including Explore for code research and Plan for planning research. A custom subagent lets you reuse your own instructions and tool choices. Its requests still consume usage; it is not a way around account limits. See the official subagent documentation.

For your first attempt, focus on one small job: finding mistakes in a file.

Step 1: Check that Claude Code is installed

Open your computer’s terminal and run:

claude --version

You should see a version number. The CLI available during preparation of this guide was 2.1.295. Your version may differ.

If Claude Code is missing, use the appropriate official installer below.

macOS, Linux, or WSL, in Bash or Zsh:

curl -fsSL https://claude.ai/install.sh | bash

Windows, in PowerShell:

irm https://claude.ai/install.ps1 | iex

These commands download and run Anthropic’s installer. Open a new terminal after installation and check claude --version again. The official quickstart also lists package-manager options and sign-in requirements.

Step 2: Create a practice folder

Use a new folder so you can try the example without touching your app.

Bash or Zsh:

mkdir claude-subagent-demo
cd claude-subagent-demo
mkdir -p .claude/agents

PowerShell:

New-Item -ItemType Directory -Path claude-subagent-demo
Set-Location claude-subagent-demo
New-Item -ItemType Directory -Path .claude/agents -Force

If that folder already exists, choose another name rather than overwriting your previous work.

Open this folder in your text editor. You will create two files:

claude-subagent-demo/
  .claude/
    agents/
      starter-reviewer.md
  checkout.js

The .claude folder may be hidden in your file manager. Your editor’s file tree can usually show it.

Step 3: Create your Claude Code subagent file

Create .claude/agents/starter-reviewer.md. Paste the following content exactly, including the first and second lines containing ---:

---
name: starter-reviewer
description: Reviews a named JavaScript file for calculation bugs and missing input checks. Use when the user requests a focused review without edits.
tools: Read, Grep, Glob
model: inherit
---

Review only the files named in your task.

For each finding, return:
1. The file and line number.
2. What is wrong, in plain English.
3. A small input example showing the problem.
4. A suggested correction, without changing the file.

Separate confirmed bugs from questions about requirements.
If you cannot verify a claim, say so.
Do not claim to have run code or tests.
Do not read .env files, credentials, or unrelated private files.
Finish with a short list of tests the developer should add.

The block between the --- lines is called frontmatter. It contains settings. The text below it contains instructions.

Setting	Purpose
name	Name you use when requesting this helper
description	Explains when this helper is relevant
tools	Lists the tools available to it
model: inherit	Requests the main session’s model

Here, Read opens files, Grep searches their contents, and Glob finds paths. There is no Bash, Edit, or Write tool in our list.

Project agents live in .claude/agents/. Personal agents shared across projects live in ~/.claude/agents/. Keep this example in the project folder so its setup is easy to see. Anthropic’s agent creation lesson explains agent configuration and project storage.

Step 4: Add a file with a known bug

Create checkout.js beside the .claude folder, not inside it:

// discountPercent is a whole percentage: 20 means 20% off.
function discountedTotal(price, discountPercent) {
  return price - discountPercent;
}

console.log(discountedTotal(200, 20));

This example contains a deliberate mistake. A 20% discount on 200 should leave 160. The function subtracts 20 directly and returns 180.

You do not need Node.js to let the reviewer inspect this file. If Node.js is already installed, you can run it yourself:

node checkout.js

The output is:

180

Keep this result in mind. It gives you something concrete to compare with the review.

Step 5: Start Claude and request the reviewer

From the claude-subagent-demo folder, start Claude Code:

claude

Complete the sign-in flow if prompted. Review any workspace-trust prompt for this practice folder.

Now paste this into the Claude conversation. This is a prompt, not a terminal command:

Use the starter-reviewer subagent to review checkout.js.
The comment defines how discountPercent should work.
Explain the calculation bug with the input 200 and 20.
Do not edit files or run commands. Return the findings and suggested tests.

Watch for a delegation entry naming starter-reviewer. A normal answer from the main assistant alone does not prove your custom helper ran. The subagent guide describes how delegation appears in the transcript.

You can also say: “Delegate this task specifically to starter-reviewer.”

Step 6: Check the result

A useful review should identify the calculation on line 3. It should explain that the function subtracts a fixed amount instead of a percentage.

An expected finding might look like this. The wording is illustrative, not a captured Claude response:

checkout.js:3
The function subtracts 20 from 200, producing 180.
For a 20% discount, the discount amount is 200 * 20 / 100 = 40.
The total should be 160.

Suggested calculation:
price * (1 - discountPercent / 100)

Suggested tests:
- 200 with 20% discount -> 160
- 200 with 0% discount -> 200
- 200 with 100% discount -> 0

The file should still contain the original function. Open it in your editor to confirm. The reviewer was asked to suggest a correction, not apply it.

It may also ask what should happen with negative prices or discounts over 100. Those are requirements questions. The incorrect percentage calculation is the confirmed bug.

For this teaching example, the corrected function is:

function discountedTotal(price, discountPercent) {
  return price * (1 - discountPercent / 100);
}

This is a small arithmetic example, not a production payment implementation. Real money calculations also need defined rounding, currency handling, and input rules.

Step 7: Use the reviewer in your own project

After the demo works, copy only starter-reviewer.md into your real project’s .claude/agents/ folder. Keep the sample checkout.js in the practice project.

Start Claude from your real project’s root and name a specific file:

Use starter-reviewer to review src/cart/calculate-total.js.
Our discount input is a whole percentage from 0 to 100.
Report confirmed calculation errors first. Do not change files.

Replace that path with a real file in your app. Give the agent the business rule it needs. A reviewer cannot reliably decide whether a number is a percentage or a currency amount if the task never explains it.

Keep the scope small at first. A clear review of one calculation is more useful than a long, vague report about an entire project.

Why is my custom subagent not working?

Problem	What to check
Claude does not find starter-reviewer	Start in the correct project; check the filename and name field
The file is ignored	Ensure it ends in .md, not .md.txt, and has both --- separators
You created the directory during a session	Restart Claude from the project folder and try again
Review reads the wrong file	Give a path relative to the project root and a focused task
Reviewer says it cannot run tests	Expected: this configuration has no terminal tool
A model or permission error appears	Read the actual error and check account or organization restrictions

Current documentation says /agents directs you to file-based setup; older releases used an interactive wizard. This tutorial uses a file so you do not need that older menu. Also, terminal command claude agents manages background sessions; it is not the same as defining a custom reviewer. See the CLI reference.

Permissions matter more than a role name

Calling a helper “read-only reviewer” is an instruction. The tool list is what limits the tools we give it. Adding Bash would let it run programs, including programs capable of writing files.

Even a read-only helper may read sensitive information if your broader settings allow it. The instruction about .env files is a request, not an access-control boundary. Use appropriate permission rules and keep secrets out of the practice folder. See Claude Code permissions and our API key protection guide.

Common questions

Do I need ten custom agents to start?

No. Start with the reviewer above. Add another helper only when you can describe a repeated task and the output you want from it.

Does a subagent always make work faster or cheaper?

No. Starting another worker and passing information has overhead. For a tiny edit, asking the main assistant may be simpler. Measure the results for your workload rather than assuming more helpers mean better work.

How should I share this reviewer with teammates?

If your team agrees, commit the project agent file to your repository. Review it like other configuration. Do not include personal credentials or private data in its instructions.

What should I create next?

Choose a role from 10 practical Claude Code subagent use cases. For how these fit with other features, read skills, MCP, subagents, and hooks compared or browse the Claude Code guides.

If your helper fails to load or run, follow Claude Code subagent not working: common problems and fixes.