How to Create Your First Claude Code Subagent

A Claude Code subagent is a specialized worker with its own context window and tools that your main session delegates a task to. You create one by writing a single Markdown file in .claude/agents/. That is the whole mechanism. A file with a few lines of YAML at the top and a system prompt below it, and Claude starts routing matching work to it.

If you already run Claude Code with a CLAUDE.md, you are most of the way there. You know how to give Claude instructions in a file. A subagent is the same idea pointed at one job. This tutorial walks you from an empty folder to a working subagent you can use today.

Most people stop at the CLAUDE.md. In our State of Claude Code 2026 analysis of public repos, only about 25% define a custom subagent at all. Among the power users who do, the median is 6 agents. This post is how you cross that line: from one config file to an actual agent system.

What a subagent actually is

A subagent is a second Claude that your main session can hand a task to. It runs in its own context window, with its own system prompt and its own set of allowed tools. When you delegate, it works on its own, then sends back a single final message. Everything it did along the way (the files it read, the commands it ran, the dead ends) stays in its context, not yours.

That isolation is the point. A long codebase search or a noisy test run can fill up your main conversation with output you will never look at again. A subagent absorbs that work and hands you only the conclusion. Your main session stays clean and focused.

This is different from CLAUDE.md. Your CLAUDE.md is a set of standing rules that load into every message of your main session, sharing one context window. A subagent is a separate worker with a separate context. For the difference between the two primitives and when to reach for each, see agent fundamentals. To get the most out of your main-session rules first, see CLAUDE.md mastery.

A complete example

Here is a real subagent you can use right now: a code reviewer. It reads the current diff with fresh, skeptical eyes and reports problems without changing anything. The frontmatter gives it a name and a description (so Claude knows when to call it) and restricts it to read-only tools, so it physically cannot edit your code. The body is its system prompt.

---
name: code-reviewer
description: Reviews the current diff for bugs, security gaps, and risky patterns. Use after writing or editing code, before committing.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a skeptical senior code reviewer. Review only the current diff.

Look, in order, for:
1. Correctness bugs that would break at runtime.
2. Security gaps: missing auth checks, unsafe input handling, leaked
   secrets, missing row-level security on a table.
3. Risky patterns: duplicated logic, swallowed errors, untested edge cases.

Rules:
- Default to flagging anything you are unsure about. A false alarm is
  cheaper than a missed bug.
- Quote the file and line number for every finding.
- Do not rewrite or edit code. You report findings only.

Your final message IS the review. Return a short list of findings, each
with file, line, severity (high, medium, low), and a one-line fix. If the
diff is clean, say so plainly in one sentence.

Save that as .claude/agents/code-reviewer.md, restart Claude Code, and the next time you ask it to review your changes (or sometimes without asking, because the description tells it to), this subagent runs in its own context and hands back a clean list of findings.

Build it step by step

You can also create subagents through the built-in /agents command, which gives you a guided interface and even generates a draft for you. But writing the file yourself is the fastest way to understand what is going on, so we will do that.

1. Create the directory

From the root of your project, make the folder Claude Code looks in for project subagents.

mkdir -p .claude/agents

This .claude/agents/ directory is the one Claude scans for definitions specific to this repository. Commit it to git and your whole team gets the same subagents.

2. Write the file

Create a Markdown file in that folder. The filename is for your own organization; the subagent's real id comes from the name field inside the file. Drop in the code-reviewer definition from above, or start with this smaller test-runner.

---
name: test-runner
description: Runs the test suite and reports failures. Use after changing code that has tests.
tools: Read, Grep, Glob, Bash
---

You are a test runner. Run the project's test suite, then report results.

Steps:
1. Find the test command (check package.json scripts, a Makefile, or a
   justfile). If you cannot find one, say so and stop.
2. Run the tests.
3. Report a one-line summary: how many passed, how many failed.
4. For each failure, give the test name, the file, and the actual error
   message. Do not paste the full log.

Your final message is the report. Keep it short. The person reading it
wants to know what broke, not the entire test output.

3. Understand the frontmatter fields

Only two fields are required: name and description. The rest are optional.

name is the subagent's id. Use lowercase letters and hyphens, like code-reviewer or test-runner. This is what you type when you call it by name.

description is the most important field, because Claude reads it to decide when to delegate. Write it as a trigger that says what the subagent does and when to use it, for example "Use after writing or editing code, before committing." A vague description means Claude never knows to call it.

tools is an allowlist of the tools the subagent may use. If you leave it out entirely, the subagent inherits every tool your main session has. Listing tools explicitly is how you keep a reviewer read-only: give it Read, Grep, Glob, Bash and no Write or Edit, and it cannot change your files.

model picks which model the subagent runs on. Accepted values include sonnet, opus, haiku, and fable, a full model id, or inherit. If you omit it, it defaults to inherit, meaning the subagent uses whatever model your main session is on. A cheaper model like haiku is a good fit for high-volume, low-stakes work.

4. Invoke it

Once the file is on disk, restart your session so Claude loads it. (Subagents you make through the /agents interface load immediately, but a file you edit by hand needs a restart.)

After that you have two ways to use it. The first is automatic: Claude reads your subagent's description and delegates on its own when your task matches. Write a good description and a lot of this just happens.

The second is explicit, for when you want to be sure. Name the subagent in your request.

Use the code-reviewer subagent on the auth changes I just made.

You can also @-mention it: type @, pick the subagent from the typeahead, and that exact subagent runs for the task.

5. Scope its tools

The tools field is your safety rail. A subagent with no Write or Edit tool cannot modify your code even if it wanted to, which is exactly what you want from a reviewer or a researcher. Give each subagent the smallest set of tools its job actually needs.

---
name: doc-checker
description: Checks that the README and docs match the current code. Use before a release.
tools: Read, Grep, Glob
---

You verify documentation against the code. Read the docs, read the
relevant source, and report any place where the docs claim something the
code no longer does. Report mismatches only. Do not edit anything.

This doc-checker has no Bash and no write tools at all. It can only read and search, which is all a documentation audit needs. If you want the inverse (inherit everything except writes) there is a disallowedTools field that removes specific tools from the inherited set instead.

6. Choose project or user level

You have two places to put a subagent, and the difference is who gets it.

Project subagents live in .claude/agents/ inside the repo. They ship with the project, so anyone who clones it and commits the folder gets the same agents. Use this for subagents that encode something about this codebase, like its test setup or its security rules.

User subagents live in ~/.claude/agents/ in your home directory. They are personal to your machine and available in every project you open. Use this for your own general-purpose helpers, like a reviewer you want everywhere.

If a project subagent and a user subagent share the same name, the project one wins. So a repo can override your personal defaults with its own version.

Good description, good delegation

The single thing that decides whether your subagent actually gets used is its description. Claude only delegates when the description matches the task in front of it, so a weak description means a subagent that sits there unused.

Write the description as a trigger, not a title. "Reviews code" is a title. "Use after writing or editing code, before committing" tells Claude exactly when to fire.

Name the moment. Phrases like "after", "before committing", "when tests fail", or "before a release" give Claude a clear hook to match against.

Keep one job per subagent. A subagent that reviews code and also runs tests and also writes docs is hard to describe and worse at all three. Split it into three, and each one gets a sharp, unambiguous description.

If a subagent never seems to run, the description is almost always the reason. Tighten it before you touch the system prompt.

What you get

You started with a CLAUDE.md and one main session doing everything. Now you have a focused worker that runs in its own context, touches only the tools you allowed, and hands back a clean answer.

The payoff compounds as you add more. A reviewer, a test runner, and a doc checker each keep their noisy work out of your main conversation, so your main session stays clear for the actual building. When several agents start coordinating, agent fundamentals covers how they fit together. For the roles most worth setting up first, see the best Claude Code subagents in 2026. And when you want a subagent to run on its own at the right moment without you asking, pair it with hooks.

If you would rather start at the far end of the ladder than build every agent by hand, the Build This Now Code Kit ($29 one-time, no subscription) ships a full team of subagents already wired into a Next.js and Supabase project: planning agents, a build pipeline, adversarial evaluators, and quality gates, sitting on top of working auth, payments, and a secure database. You get the agent system, not just the agents.

FAQ

Where do Claude Code subagents live?

In .claude/agents/ inside your repo for a project subagent (commit it to share with your team), or in ~/.claude/agents/ for a user subagent available in every project. Each Markdown file is one subagent, and its id comes from the name field, not the filename.

What goes in a subagent file?

YAML frontmatter followed by a system prompt. Only name and description are required. Optional fields include tools (an allowlist; inherits every tool if omitted) and model (defaults to inherit). The Markdown body below the frontmatter is the subagent's system prompt.

How does Claude decide to use a subagent?

It reads the description of every subagent and delegates automatically when a task matches, which is why the description should read like a trigger. You can also invoke one explicitly by saying "Use the code-reviewer subagent on the auth changes" or by @-mentioning it.

Why use a subagent instead of just adding rules to CLAUDE.md?

CLAUDE.md shapes every message in your main session and shares one context window. A subagent runs in its own separate context with its own tools, does one scoped job, and returns only its final message, so noisy work stays out of your main conversation.

Do I need to restart Claude Code after adding a subagent?

If you create or edit the file directly on disk, yes, restart so it loads. Subagents created through the /agents interface take effect immediately. Run /agents and check the Library tab to confirm yours is registered.