Claude Code Subagents: How to Create, Scope and Use Them (Nov 2026)

A Claude Code subagent is a helper Claude hands a side task to. It runs in its own context window with its own prompt, tools and model, and sends back only a summary. To make one, save a Markdown file with name and description front matter in .claude/agents/ (this project) or ~/.claude/agents/ (all your projects).

Subagents keep your main conversation clean. They are also a way to give a task fewer tools than you have. That second part is where most people get it wrong: a subagent with no tools line gets every tool your session has, including every MCP tool. This guide covers how to define one, how to scope it, and when a subagent, a skill or an MCP server is the right fit.

Everything about how Claude Code behaves here comes from the Claude Code subagents docs, checked on 8 November 2026.

What is a Claude Code subagent?

The docs define it like this: "Subagents are specialized AI assistants that handle specific types of tasks. Use one when a side task would flood your main conversation with search results, logs, or file contents you won't reference again: the subagent does that work in its own context and returns only the summary."

Three things make a subagent different from just asking Claude:

• Its own context. "Each subagent starts with a fresh, isolated context window. It doesn't see your conversation history." It does load your CLAUDE.md files and a git status snapshot.
• Its own tools and permissions. You can give it a short tool list, block tools, or pick a permission mode.
• Its own model. A cheap, fast model for searching; a stronger one for review.

Claude Code ships a few built-in subagents that Claude uses on its own:

Built-in	What it's for	Tools
Explore	"file discovery, code search, codebase exploration"	Read-only: Write and Edit are denied
Plan	Research in plan mode before Claude shows you a plan	Read-only: Write and Edit are denied
General-purpose	"complex research, multi-step operations, code modifications"	Every tool available to subagents

The docs say each built-in "inherits the parent conversation's permission rules". You define custom subagents for jobs you keep handing out with the same instructions.

Where subagent files live

A subagent is a Markdown file: front matter on top, the system prompt below. Where you save it sets who gets it. When two subagents share a name, the higher-priority one wins:

Location	Scope	Priority
Managed settings	Your whole organization	1 (highest)
--agents flag	This session only	2
.claude/agents/	This project (commit it to share with your team)	3
~/.claude/agents/	All your projects	4
A plugin's agents/ folder	Wherever the plugin is enabled	5 (lowest)

Claude Code scans both agents folders recursively, so subfolders are fine.

How to create a Claude Code subagent

There are two ways. Ask Claude ("create a subagent that reviews my diffs for security issues, read-only") and it writes the file. Or write the file yourself. This is the docs' own example:

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

Save it as .claude/agents/code-reviewer.md. The file name doesn't have to match name.

In current versions, /agents only reminds you to ask Claude or edit those folders. The docs note that on v2.1.197 and earlier it opened an interactive wizard instead.

For a one-off session, pass subagents as JSON. They aren't saved to disk:

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

The front matter fields

"Only name and description are required." Field names are camelCase and must match exactly: the docs warn that "Claude Code ignores a field it doesn't recognize without reporting an error." A typo like disallowed-tools fails silently, and your tool limit is gone.

The fields that matter most:

Field	What it does
name	The subagent's id, such as code-reviewer. No : allowed.
description	When Claude should hand work to it. Claude matches tasks against this.
tools	Allowlist of tools. Leave it out and the subagent "Inherits every tool available to subagents".
disallowedTools	Denylist, removed from the inherited or listed tools.
model	sonnet, opus, haiku, fable, a full model id, or inherit.
permissionMode	default, acceptEdits, auto, dontAsk, bypassPermissions or plan.
mcpServers	MCP servers for this subagent only (by name or defined inline).
skills	Skills whose full text is loaded into the subagent at startup.
hooks	Hooks that run only for this subagent, for example a PreToolUse check.
maxTurns	Stops the subagent after this many turns.
isolation	worktree runs it in a temporary git worktree, a separate copy of the repo.
memory	Keeps notes across sessions: user, project or local.
background	true keeps it running in the background.

There are a few more (effort, color, omitClaudeMd, initialPrompt, autoCompactWindow); the docs list them all.

Model selection

Pick the model by job: haiku for searching and summarizing, sonnet or opus for review and design. If you leave model out, Claude Code checks, in order: a model Claude passes when it calls the subagent, the model field, the CLAUDE_CODE_SUBAGENT_MODEL environment variable, then your main conversation's model. To force one model on every subagent, also set CLAUDE_CODE_SUBAGENT_MODEL_FORCE to 1 (v2.1.257 or later).

How to use a Claude Code subagent

• Let Claude decide. Claude delegates "based on the task description in your request, the description field in subagent configurations, and current context." Put "use proactively" in the description to make that happen more often.
• Ask by name. "Use the code-reviewer subagent to check my last commit."
• @-mention it. Type @ and pick it, or write @agent-code-reviewer.
• Run your whole session as it. claude --agent code-reviewer.

Subagents Claude starts from your main conversation run in the background by default, so you can keep working. Their permission prompts still show up in your main session. By default a subagent can start its own subagents, up to three levels deep; set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH to 1 to turn that off.

Limit what a subagent can reach

This is the part to get right. A subagent's reach is its tool list, its MCP servers and its permission mode. Each one has a safe setting and a risky default.

Tools: allowlist beats denylist

An allowlist is the tight option. The docs say a subagent with tools: Read, Grep, Glob, Bash "can't edit files, write files, or use any MCP tools."

A denylist is looser. With disallowedTools: Write, Edit, the subagent "keeps Bash, MCP tools, and the rest of its pool." Bash can still write files, so a denylist without Bash isn't read-only.

If you set both, the denylist is applied first, and a tool in both lists is removed. One more trap: disallowedTools: Bash(git push *) removes all of Bash from the subagent, not just git push. To block only some commands, use a deny rule in your settings instead; the docs say a rule like Bash(git push *) in permissions.deny "applies to the main conversation and to subagents." How to limit MCP tools covers deny rules in detail.

MCP tools in a subagent

"Subagents inherit the built-in tools and MCP tools available in the main conversation." So with no tools line, a subagent built for one small job can call your GitHub, database or email server too. Patterns from the docs:

You want	Use
Only one server's tools	tools: mcp__github__* (plus the built-ins it needs)
Everything except one server	disallowedTools: mcp__github__*
No MCP tools at all	disallowedTools: mcp__*

You can also give a subagent a server your main session doesn't have, with mcpServers. An inline server "is connected when the subagent starts" and "disconnected when it finishes", and "the parent conversation doesn't" get its tools. That's a clean way to keep a risky server, like a browser or a database with write access, inside one narrow helper:

---
name: browser-tester
description: Runs browser checks against the local dev server. Use for UI testing.
tools: Read, mcp__playwright__*
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
---

Check the server before you wire it in. Our Playwright MCP review and Claude Code MCP setup cover that step. Inline servers in a project's .claude/agents/ only load after you trust the folder.

Skills in a subagent

The skills field preloads skills, but it doesn't limit them. In the docs' words: "without it, the subagent can still discover and invoke project, user, and plugin skills through the Skill tool." To stop that, leave Skill out of tools or add it to disallowedTools.

Permission mode

Leave permissionMode unset and the subagent uses your main session's mode. Setting it doesn't always win: "When the main conversation is in bypassPermissions, acceptEdits, or auto mode, the subagent runs in that same mode and Claude Code ignores the permissionMode you set." A subagent can't loosen your session into bypassPermissions either; it only runs that way when the main conversation does.

Hooks for checks a tool list can't express

A PreToolUse hook can inspect every call before it runs. The docs' example lets a database helper use Bash, but only for read-only queries:

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

Note: subagents that come from a plugin ignore hooks, mcpServers and permissionMode. The docs say this is "For security reasons". So a plugin subagent can't bring its own MCP server or raise its permission mode, but it can't use a hook to limit itself either.

Subagent vs skill vs MCP server: which to use when

They answer different questions. A subagent is who does the work, a skill is how to do it, and an MCP server is what Claude can reach.

	Subagent	Skill	MCP server
What it is	A helper with its own context, prompt, tools and model	A folder with a SKILL.md of instructions and maybe scripts	A separate program that offers tools and data
Use it for	Side tasks with noisy output; tasks that need fewer tools	A repeatable workflow or house style	Access to an app, API or database
Where it runs	Separate context, returns a summary	In your main conversation	Its own process or a remote service
Context cost	Description only; the work stays out of your context	Description every turn, body when used	Tool definitions, unless tool search defers them
Main risk	No tools line means every tool, MCP included	Hidden instructions, scripts, broad allowed-tools	Wide tokens, risky tools, prompt injection

The docs give the rule of thumb. Use subagents when "The task produces verbose output you don't need in your main context", when "You want to enforce specific tool restrictions or permissions", and when "The work is self-contained and can return a summary." Stay in the main conversation for back-and-forth and quick changes. "Consider Skills instead when you want reusable prompts or workflows that run in the main conversation context."

They also combine well:

• Subagent + MCP server: a db-reader subagent is the only place your database server's tools exist.
• Subagent + skill: a reviewer subagent preloads your team's review-checklist skill with skills:.
• Skill that runs as a subagent: a skill with context: fork in its front matter runs in a separate subagent. See Claude Code skills.

Frequently asked questions

What are Claude Code subagents?

Helpers that Claude hands side tasks to. Each runs in its own context window with its own system prompt, tools, permissions and model, and returns a summary to your main conversation. You define custom ones as Markdown files.

How do I create a Claude Code subagent?

Ask Claude ("create a subagent that reviews my diffs for security issues, read-only") or save a Markdown file with name and description front matter in .claude/agents/. For a one-off session, pass it as JSON with claude --agents.

How do I use a subagent in Claude Code?

Let Claude pick it from the description, ask for it by name, @-mention it (@agent-code-reviewer), or run the whole session as it with claude --agent code-reviewer.

Where are Claude Code subagents stored?

Project subagents go in .claude/agents/, personal ones in ~/.claude/agents/, and plugin subagents in the plugin's agents/ folder. Session-only subagents can be passed with claude --agents '<json>'. Managed settings can deploy them for a whole organization.

Do subagents get my MCP servers?

Yes, unless you limit them. Subagents inherit the MCP tools of your main conversation. Use a tools allowlist, disallowedTools: mcp__*, or give one subagent its own server with mcpServers.

How do I make a read-only subagent?

Set tools: Read, Grep, Glob. Add Bash only if it needs to run commands, because Bash can still change files. disallowedTools: Write, Edit alone is not read-only.

Which model does a subagent use?

The one in its model field (sonnet, opus, haiku, fable, a full model id, or inherit). Without one, it uses CLAUDE_CODE_SUBAGENT_MODEL if set, otherwise your main conversation's model.

Can a subagent start other subagents?

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

Should I use a subagent or a skill?

Use a subagent when the work is noisy, self-contained or needs fewer tools. Use a skill for a repeatable workflow you want to run in your main conversation. You can preload skills into a subagent with the skills field.

What is a forked subagent?

A fork is a subagent that "inherits the entire conversation so far instead of starting fresh". You start one with /subtask <task>. A normal subagent starts with an empty context and only the task Claude gives it.