Claude Code Subagents Guide: .claude/agents Files, Tools, Models and Examples

Claude Code subagents are helper AIs that run in their own context window. Each one has its own instructions, tools and model, and hands back only a short result.

They keep your main chat clean and let you route cheap work to cheaper models. This guide shows how to build them in .claude/agents/, every frontmatter field, and when a skill is the better choice.

What Claude Code subagents are

A subagent is a specialist that Claude can hand a task to. It starts with a fresh context window, its own system prompt and its own tool list. When it is done, only its final result comes back to your main conversation.

This matters because long logs, search results and file dumps no longer fill up your main chat. Your main session stays focused, and you get more useful work out of each context window.

Why developers use them

• Save context: noisy work like test runs or log digging happens somewhere else.
• Limit tools: a reviewer can be read-only, so it can never edit a file.
• Reuse setups: commit one file and the whole team gets the same helper.
• Cut cost: send simple jobs to Haiku while your main chat stays on a bigger model.
• Run in parallel: several independent research tasks can happen at once.

Note: Subagent requests count toward the same usage limits as your main conversation. Check my Claude Code pricing guide if you are on a tight plan.

The built-in subagents

Claude Code ships with several subagents that are on by default. You do not need to create anything to use them.

With a Claude subscription, a Console account or an LLM gateway, Explore runs on the model the opus alias points to. On Bedrock, Google Cloud and Microsoft Foundry it stays on your main model.

To switch built-ins off, deny Agent(Explore) in permissions.deny, or set CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 to remove only Explore and Plan.

How to create your first subagent

Older guides tell you to open the /agents wizard. That wizard was removed in v2.1.198. Typing /agents now just explains where it went. Here is the current way.

1. Make the folder. In your repo root, run mkdir -p .claude/agents. Use ~/.claude/agents instead if you want the agent in every project.
2. Create the file. Add .claude/agents/code-reviewer.md. The file name does not have to match the agent name, but matching keeps things tidy.
3. Add frontmatter. At the top, write a name and a clear description of when Claude should use it.
4. Limit tools and pick a model. Add tools: Read, Grep, Glob and model: sonnet for a read-only reviewer.
5. Write the system prompt. Below the closing ---, describe the role, the steps and the output format.
6. Save and test. The file watcher picks up edits within seconds. Ask: “Use the code-reviewer subagent to check my last commit.”

Tip: You can skip the typing. Ask Claude: “Create a project subagent called test-runner that runs our tests with Bash and fixes failures.” It will write the file for you to review.

The basic file format

---
name: code-reviewer
description: Reviews code for quality and best practices. Use proactively after code changes.
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

A subagent gets only this system prompt plus basic environment details like the working directory. It does not get the full Claude Code system prompt.

Where subagent files live

Subagents can come from five places. When two share a name, the higher priority wins.

• Subfolders: are scanned and used only for tidiness. In plugins, the path becomes part of the name, like my-plugin:review:security.
• Plugin limits: plugin subagents ignore hooks, mcpServers and permissionMode.
• Restart needed: only when you create a brand new agents folder after the session started.

For a quick test without saving a file, pass JSON with the --agents flag. It lasts for that session only.

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Frontmatter fields explained

Field names are case-sensitive camelCase. Unknown fields are silently ignored, so a typo will not throw an error. These are the fields you will use most.

How the model is picked

1. Per call: a model value Claude passes when it spawns the agent.
2. Frontmatter: the agent’s own model field.
3. Env var: CLAUDE_CODE_SUBAGENT_MODEL.
4. Fallback: your main conversation’s model.

To force one model on every subagent, set both CLAUDE_CODE_SUBAGENT_MODEL and CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1. If a mode is set on the main chat, bypassPermissions, acceptEdits and auto mode override the agent’s permissionMode. My auto mode guide explains those modes.

Ready-to-use subagent examples

Read-only code improver

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Database reader that blocks writes

This one combines a tool limit with a hook. The hook script exits with code 2 to block any write query.

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

Make the script executable with chmod +x. My Claude Code hooks guide shows how hook scripts read JSON from stdin.

Browser tester with its own MCP server

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

The Playwright server only loads for this agent, so it does not crowd your main tool list. See my MCP setup guide for more on MCP servers.

How to run, background and resume subagents

Four ways to call a subagent

• Automatic: Claude picks one when your task matches its description. Words like “use proactively” help.
• By name: “Use the test-runner subagent to fix failing tests.”
• @-mention: @"code-reviewer (agent)" look at the auth changes guarantees that agent runs.
• Whole session: claude --agent code-reviewer runs your entire session as that agent.

Foreground and background

By default, subagents Claude starts from the main chat run in the background. Their permission prompts show in your main session with the agent’s name. Press Ctrl+B to send a running task to the background.

Background agents get a slightly smaller built-in tool set, but all MCP tools remain. In 2.1.318, background subagents started moving long shell commands to the background after 3 minutes.

Resuming and history

Each call starts a new instance. Claude can resume a finished one with SendMessage, using its ID or name. Explore and Plan are one-shot and cannot be resumed.

Since 2.1.319, /tasks has an “Earlier in this session” row. You can reopen a finished subagent and message it, even after a restart.

Limits to know

• Nesting: subagents can spawn subagents up to three levels deep. Change it with CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH.
• Concurrency: 20 running at once, set by CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS.
• Context: a subagent does not see your chat. It does get CLAUDE.md files, git status and preloaded skills.
• Descriptions: keep all custom descriptions under about 15,000 tokens in total, or you get a startup warning.

Subagents vs skills: which to use

Both package reusable know-how, so people mix them up. The key difference is where the work runs.

• Combine them: list skills in a subagent’s skills field to preload them.
• Reverse it: a skill with context: fork runs inside an agent you name.
• Stay in main chat: for quick, back-and-forth edits, a subagent just adds overhead.

Read my Claude skills guide to build the skill side.

Troubleshooting subagents

Claude never uses my subagent

Make the description specific and add “use proactively” if you want automatic use. You can also force it with an @-mention.

A field like tools or model is ignored

Check the spelling and case. Unknown fields are silently ignored, so Tools or disallowed_tools will not work.

The new agent does not show up

Edits load within seconds, but a new agents folder created mid-session needs a restart. Also check that no higher-priority location uses the same name.

My plugin agent’s hooks do not run

Plugin subagents do not support hooks, mcpServers or permissionMode. Copy the agent into .claude/agents/ if you need those fields.

Inline MCP servers do not load

Inline servers in a project’s .claude/agents/ files load only after you trust that folder.

My permissionMode setting has no effect

If the main session is in auto, accept edits or bypass mode, that mode wins. Plan mode in the main chat also keeps subagents in plan mode.

Frequently Asked Questions

What happened to the /agents command?

The interactive wizard was removed in v2.1.198. Typing /agents now explains where it went, and you create agents by asking Claude or editing .claude/agents/.

Which fields are required in a subagent file?

Only name and description. Everything else, including tools and model, is optional.

Can a subagent use a different model from my main chat?

Yes. Set model: haiku, sonnet, opus, fable or a full model ID in the frontmatter.

Can subagents start other subagents?

Yes, up to three levels below the main conversation by default. Set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 to turn nesting off.

How many subagents can run at once?

Twenty by default. You can change it with CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS.

Do subagents remember things between runs?

Not by default. Add a memory field set to user, project or local to give an agent a persistent memory folder.

Should I commit subagent files to git?

Yes, for project agents in .claude/agents/. That way your whole team gets the same helpers, and personal ones stay in ~/.claude/agents/.

Sources

• Claude Code docs: Create custom subagents
• Claude Code changelog on GitHub
• Claude Code docs: Skills
• Releasebot: Anthropic updates