Coding Agents

Claude Code subagent builder

Q: Where do Claude Code subagent files go?

In .claude/agents/ inside your project for subagents the team shares, or ~/.claude/agents/ for your own in every project. Both folders are read recursively, so subfolders are fine. If two subagents share a name, managed settings win, then the --agents flag, then the project, then your user folder, then plugins. Edits are picked up within seconds, but a newly created agents folder needs a restart.

Q: How do I create a subagent in Claude Code?

Save a Markdown file with name and description frontmatter in .claude/agents/, or ask Claude to write one for you. Many guides still say to run /agents, but its setup wizard only exists in Claude Code 2.1.197 and earlier; current versions just print a reminder to ask Claude or edit the folder. New and edited files load within seconds, without a restart, unless the agents folder didn’t exist when the session started.

Q: Which frontmatter fields are required?

Only name and description. Without a name, Claude Code treats the file as documentation; with a name but no description, it skips the file. It also skips files whose YAML doesn’t parse and files where --- isn’t the first line, and none of these show an error in the session. Paste your file into the checker above to find out which one applies.

Q: What do model: haiku, sonnet, opus and inherit mean?

They’re aliases. On the Anthropic API, opus runs Claude Opus 5.5, sonnet Claude Sonnet 5.5, haiku Claude Haiku 5.5 and fable Claude Fable 5.1; other platforms can map them to older versions. inherit uses the main conversation’s model. If the main conversation already runs, say, an Opus model, opus gives the subagent that exact model.

Build a Claude Code subagent file with the right tools, model and frontmatter, starting from a code reviewer, test runner or security auditor, or paste an existing file to see why it isn’t loading. It’s free and runs in your browser.

Save as .claude/agents/code-reviewer.md

code-reviewer.md

---
name: code-reviewer
description: Reviews code changes for bugs, security problems and readability. Use proactively after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer. You read code; you never change it.

When invoked:
1. Run `git diff HEAD` to see what changed. If the task names files, review those instead.
2. Read enough of the surrounding code to understand each change.
3. Review, then report.

Check for:
- Bugs: wrong logic, unhandled errors, off-by-one mistakes, race conditions
- Security: unvalidated input, injection, secrets in code, unsafe defaults
- Readability: unclear names, duplicated code, functions doing too much
- Tests: changed behaviour without a test

Report findings grouped as Must fix, Should fix and Consider. For each one, give the file and line, the problem in one sentence, and a concrete fix. If the changes look good, say so in one line.

claude --agents

{
  "code-reviewer": {
    "description": "Reviews code changes for bugs, security problems and readability. Use proactively after writing or modifying code.",
    "prompt": "You are a senior code reviewer. You read code; you never change it.\n\nWhen invoked:\n1. Run `git diff HEAD` to see what changed. If the task names files, review those instead.\n2. Read enough of the surrounding code to understand each change.\n3. Review, then report.\n\nCheck for:\n- Bugs: wrong logic, unhandled errors, off-by-one mistakes, race conditions\n- Security: unvalidated input, injection, secrets in code, unsafe defaults\n- Readability: unclear names, duplicated code, functions doing too much\n- Tests: changed behaviour without a test\n\nReport findings grouped as Must fix, Should fix and Consider. For each one, give the file and line, the problem in one sentence, and a concrete fix. If the changes look good, say so in one line.",
    "tools": [
      "Read",
      "Grep",
      "Glob",
      "Bash"
    ],
    "model": "inherit"
  }
}

For one session only: claude --agents '<json>'. The body becomes prompt; color isn’t accepted here.

Checking…

Everything stays in your browser. Your draft is saved on this device.

Steps

How to use the Claude Code subagent builder

Pick an example close to what you want, or start blank.
Name the subagent and write a description that says when Claude should use it.
Choose its tools, model and any limits, then write its system prompt.
Fix anything the checks flag, then download the file into .claude/agents/ (or ~/.claude/agents/) and ask Claude to use it.
To check a file you already have, switch to “Check a subagent file” and paste it.

Method

How it works

A Claude Code subagent is a Markdown file: YAML frontmatter between two --- lines, then a body that becomes the subagent’s system prompt. When Claude meets a task that matches the description, it hands the task to the subagent, which works in its own context window with its own tools and returns only its result. That keeps long searches, logs and test output out of your main conversation. For when a subagent saves tokens and when it costs more, read the Claude Code subagents guide.

The fields that do the work

description is routing, not documentation: it’s what Claude reads when deciding whether to delegate, so say what the subagent does and when to use it. Descriptions load into every session, and Claude Code warns at startup when your subagents’ descriptions add up to more than 15,000 tokens, so keep detail in the body.

tools is an allowlist and disallowedTools a denylist. Leave both out and the subagent inherits every tool available to subagents, including MCP tools. If you set both, the denylist is applied first. When no entry in tools matches a real tool, for example because of a typo like read, Claude Code refuses to start the subagent. Some tools never reach a subagent, such as AskUserQuestion, and subagents that run in the background, the default in interactive sessions, keep a shorter list of built-in tools.

model takes an alias (sonnet, opus, haiku, fable), inherit, or a full model ID. Routing a read-only research or test-running subagent to Haiku is the usual way to cut its cost.

Mistakes that fail silently

Claude Code doesn’t report a bad subagent file in the session. It skips the file when there’s no name, no description, a name that starts with - or contains :, YAML that doesn’t parse, or an opening --- that isn’t the first line. The most common YAML error is an unquoted colon in the description, as in description: Use when: tests fail. Field names are camelCase and must match exactly, and any field Claude Code doesn’t recognise is ignored, so allowed-tools (the skills spelling) or max_turns does nothing. The checker looks for all of these and suggests the field you probably meant.

What a subagent starts with

A subagent doesn’t see your conversation, earlier tool results or the files Claude has read. It gets its own system prompt (your body, not Claude Code’s), the task Claude writes for it, your CLAUDE.md files and a git status snapshot. The built-in Explore and Plan subagents skip CLAUDE.md and git status to stay fast; your own subagents can skip CLAUDE.md with omitClaudeMd: true from Claude Code 2.1.271. Because the subagent starts fresh, the body should say what to do, in what order, and what the report should look like.

Built-in subagents

Claude Code ships with Explore (fast, read-only codebase search), Plan (research during plan mode), general-purpose (every tool, for multi-step work), a catch-all agent named claude, and helpers such as statusline-setup and claude-code-guide. A file of your own named Explore replaces the built-in one, which is how you can run exploration on a cheaper model.

Everything here runs in your browser, and nothing you type or paste is sent anywhere. The rules were checked against Claude Code’s documentation on 2026-10-12, when 2.1.296 was the latest release. For reusable prompts you trigger yourself, use the slash command builder.

Examples

Worked examples

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews code changes for bugs, security problems and readability. Use proactively after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer. You read code; you never change it.

When invoked:
1. Run `git diff HEAD` to see what changed. If the task names files, review those instead.
2. Read enough of the surrounding code to understand each change.
3. Review, then report.

Check for:
- Bugs: wrong logic, unhandled errors, off-by-one mistakes, race conditions
- Security: unvalidated input, injection, secrets in code, unsafe defaults
- Readability: unclear names, duplicated code, functions doing too much
- Tests: changed behaviour without a test

Report findings grouped as Must fix, Should fix and Consider. For each one, give the file and line, the problem in one sentence, and a concrete fix. If the changes look good, say so in one line.

A read-only reviewer: Bash lets it run git diff, and leaving out Edit and Write means it can’t change files. model: inherit keeps it on your session’s model.

.claude/agents/test-runner.md

---
name: test-runner
description: Runs the test suite and reports only the failing tests with their errors. Use after code changes or when asked to run tests.
tools: Bash, Read, Grep, Glob
model: haiku
maxTurns: 15
color: green
---

You run tests and report the results. You don't fix code.

1. Find the test command: check package.json scripts, Makefile, pyproject.toml, Cargo.toml or go.mod. If the task names a command or a test file, use that.
2. Run it. If it takes a filter for one file or test, use the narrowest one that covers the task.
3. Read the output and report back.

Your report:
- One line: how many tests passed, failed and were skipped.
- For each failure: the test name, the file and line, and the key lines of the error. Leave out stack frames from libraries.
- If the run itself failed (missing dependency, syntax error), say what failed and the command you ran.

Keep the report short. Don't paste full logs.

Test output is long and mostly noise, so this one runs on Haiku, stops after 15 turns and reports only failures.

Frontmatter fields

Field	Values	What it does
name	lowercase-and-hyphens	Required. No `:`, can’t start with `-`, at most 256 characters. The file name doesn’t have to match.
description	text	Required. When Claude should delegate to it.
tools	Read, Grep, Glob, Bash …	Allowlist. Omit to inherit every tool available to subagents. `mcp__github` covers a whole MCP server.
disallowedTools	Write, Edit …	Denylist, applied before `tools`. A specifier such as `Bash(git push *)` still removes the whole tool.
model	sonnet, opus, haiku, fable, inherit, or a full ID	Omitted: the subagent model order applies (see the FAQ).
permissionMode	default, acceptEdits, auto, dontAsk, bypassPermissions, plan	Ignored when the main conversation is in bypassPermissions, acceptEdits or auto mode.
maxTurns	a whole number	Stops after that many agentic turns; the output is marked partial.
skills	list of skill names	Preloads each skill’s full content (first 32).
mcpServers	list	Server names already configured, or inline server definitions.
hooks	map of events	Hooks that run only while this subagent is active.
memory	user, project, local	A persistent notes folder that survives between sessions.
background	true	Always run in the background.
effort	low, medium, high, xhigh, max	Overrides the session effort level.
isolation	worktree	Runs in a temporary git worktree.
omitClaudeMd	true	Skips your user, project and local CLAUDE.md files. Claude Code 2.1.271+.
color	red, blue, green, yellow, purple, orange, pink, cyan	Display colour in the task list.
initialPrompt	text	First turn when the agent runs as the main session (--agent).
experimental	cacheTtl: 5m or 1h	Prompt cache lifetime for this subagent. Claude Code 2.1.248+.

FAQ

Frequently asked questions

Where do Claude Code subagent files go?

In .claude/agents/ inside your project for subagents the team shares, or ~/.claude/agents/ for your own in every project. Both folders are read recursively, so subfolders are fine. If two subagents share a name, managed settings win, then the --agents flag, then the project, then your user folder, then plugins. Edits are picked up within seconds, but a newly created agents folder needs a restart.

How do I create a subagent in Claude Code?

Save a Markdown file with name and description frontmatter in .claude/agents/, or ask Claude to write one for you. Many guides still say to run /agents, but its setup wizard only exists in Claude Code 2.1.197 and earlier; current versions just print a reminder to ask Claude or edit the folder. New and edited files load within seconds, without a restart, unless the agents folder didn’t exist when the session started.

Which frontmatter fields are required?

Only name and description. Without a name, Claude Code treats the file as documentation; with a name but no description, it skips the file. It also skips files whose YAML doesn’t parse and files where --- isn’t the first line, and none of these show an error in the session. Paste your file into the checker above to find out which one applies.

What do model: haiku, sonnet, opus and inherit mean?

They’re aliases. On the Anthropic API, opus runs Claude Opus 5.5, sonnet Claude Sonnet 5.5, haiku Claude Haiku 5.5 and fable Claude Fable 5.1; other platforms can map them to older versions. inherit uses the main conversation’s model. If the main conversation already runs, say, an Opus model, opus gives the subagent that exact model.

Which model does a subagent use if I leave model out?

Claude Code checks, in order: a model Claude passes when it starts the subagent, the model field, the CLAUDE_CODE_SUBAGENT_MODEL environment variable, then the main conversation’s model. So with no field and no variable set, a subagent runs on the same model as your session. To put every subagent on one model regardless of its file, also set CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 (Claude Code 2.1.257 or later).

Why isn’t Claude using my subagent?

First check that it loaded: run the file through the checker, or claude plugin validate .claude/agents. Then look at the description, which is the only thing Claude reads when deciding to delegate: say what the subagent does and when, and add “use proactively” to encourage it. To force it for one task, @-mention it, for example @agent-code-reviewer.

Do subagents save tokens or cost more?

Both, depending on the task. A subagent sends its own requests, which count toward the same usage limits, and it starts without your conversation, so it may need to re-read files. It saves your main context when a task produces lots of output you don’t need, such as test logs or searches, and costs less when you route it to a cheaper model like Haiku.

What’s the difference between a subagent and a slash command?

A subagent is a separate worker with its own context, tools and system prompt that returns a summary. A slash command, now part of skills, is a reusable prompt that runs in your main conversation, unless it sets context: fork to run in a subagent. Use a subagent to isolate noisy or restricted work, and a command for a workflow you trigger yourself.

Read

Glossary

Key terms

What is a subagent in Claude Code?