How to Define Claude Code Subagents

A Claude Code subagent definition needs only two keys: name and description. Where the files go, how to restrict tools, and how the model gets chosen.

A subagent is a specialist helper that runs in its own context, separate from your main conversation. It works through bulky output you won’t read again, such as search results or logs, and hands back only a summary, so your main conversation stays clean. This guide covers the built-in subagents, where definition files go, the file format, how subagents get invoked, model and tool settings, and cost. For what went wrong when we ran many in parallel, see Subagent Failures in Parallel Runs. In our test environment (macOS, Claude Code 2.1.306, on 2026-10-22), we put a definition file into a dummy todo app and validated its format. We did not run a session that actually invokes the subagent (not run).

Built-in subagents

Explore and Plan start without your CLAUDE.md files.

Source: https://code.claude.com/docs/en/sub-agents (checked 2026-10-22)

Where definitions live

A subagent is a Markdown file with YAML frontmatter. Either ask Claude to write one (“create a read-only reviewer in ~/.claude/agents/”) or write the file yourself. In current versions, /agents doesn’t open an editor; it prints a reminder to ask Claude or edit the agents directories directly. Up to v2.1.197 it opened a wizard.

When two subagents share a name, the higher-priority one wins. Subagents are identified by the frontmatter name, not the filename. Added or edited files are picked up within a few seconds, but if you create an agents directory that didn’t exist when the session started, restart to load it.

Source: https://code.claude.com/docs/en/sub-agents (checked 2026-10-22)

The definition file

Here is a read-only code reviewer for a dummy todo app, saved as .claude/agents/readonly-reviewer.md:

---
name: readonly-reviewer
description: Read-only code reviewer for the todo app. Use proactively after code changes, or when the user asks for a review of a diff. Do not use for writing fixes or running migrations.
tools: Read, Grep, Glob
model: sonnet
maxTurns: 20
---

You review changes in the todo app. You never edit files.

1. Read the list of changed files passed to you by the caller.
2. Read those files and their tests.
3. Report findings as a list: file:line, severity (high / medium / low), and one sentence on why.
4. If you find nothing, say "No findings" and list what you checked.

The body becomes the subagent’s system prompt. It does not receive Claude Code’s own system prompt.

The main frontmatter keys are below. Only name and description are required. Multi-word keys use camelCase, as in maxTurns.

Source: https://code.claude.com/docs/en/sub-agents (checked 2026-10-22)

Validate the format

claude plugin validate .claude/agents checks definitions without starting a session. We ran it on 2026-10-22 with 2.1.306. The example above returned Validation passed. A file with an unclosed quote returned:

✘ Found 1 error:

  ❯ frontmatter: YAML frontmatter failed to parse: YAML Parse error: Unexpected character. At runtime this agent does not load at all — with no frontmatter name it is treated as a co-located reference document and skipped.

A subagent with broken YAML doesn’t load at all. Files with tool instead of tools, modle instead of model, or a name containing : all passed the validator. The docs say Claude Code skips, at runtime, any file whose name starts with -, contains :, or is longer than 256 characters, and writes an error to the debug log. It passes the check but never loads. The docs also say unknown keys are ignored without an error, and that a misspelled key shows up in the claude --debug log as does not recognize or apply (not run).

Descriptions and invocation

Claude picks a subagent from your request, each subagent’s description, and the current context. To encourage proactive delegation, the docs suggest phrases like “use proactively” in the description. If your subagents’ descriptions add up to more than 15,000 tokens, you get a warning at startup. Keep descriptions short and put details in the body.

There are three ways to invoke one explicitly:

• Ask in plain language: “Use the readonly-reviewer subagent to review my changes”. Claude decides whether to delegate
• @-mention it: @"readonly-reviewer (agent)" look at the auth changes. That subagent is guaranteed to run for the task
• Whole session: the --agent flag or the agent setting runs the session itself as that subagent

Source: https://code.claude.com/docs/en/sub-agents (checked 2026-10-22)

Choosing the model

The model is resolved in this order:

1. The model Claude passes for that invocation
2. The definition’s model (inherit means the main conversation’s model)
3. The CLAUDE_CODE_SUBAGENT_MODEL environment variable
4. The main conversation’s model

If you leave model out, the subagent usually runs on the main conversation’s model, so a simple search runs on a top-tier model if that’s what you’re chatting with. Set the model explicitly in the definition. /tasks shows which model a subagent is running on (v2.1.242 or later).

Source: https://code.claude.com/docs/en/sub-agents (checked 2026-10-22)

Tools and permissions

• Tools: without tools, a subagent inherits the built-in and MCP tools of the main conversation, except a few such as AskUserQuestion, which no subagent gets
• MCP: tools: mcp__github__* grants only that server’s tools. disallowedTools: mcp__* removes every MCP tool
• disallowedTools: Bash(git push *) removes Bash entirely. To block specific commands, use permissions.deny in settings; that rule applies to subagents too
• Permission mode: without permissionMode, a subagent inherits the main conversation’s mode. When the main conversation is in bypassPermissions, acceptEdits or auto mode, the subagent’s permissionMode is ignored

Since v2.1.283, interactive sessions start in auto mode by default, and in auto mode a subagent’s permissionMode is ignored. So enforce read-only access with tools, not permissionMode. That’s why the example limits tools to Read, Grep, Glob and leaves Bash out. For permission rules, see Claude Code settings.json Permissions: A Cheat Sheet.

Sources: https://code.claude.com/docs/en/sub-agents and https://code.claude.com/docs/en/permission-modes (checked 2026-10-22)

Cost

Each subagent keeps its own context and sends its own requests, and those requests count toward the same usage limits as your main conversation. Run many at once and usage grows with them. A skill can also run as a subagent; see How to Create Claude Code Skills (SKILL.md).

Summary

• A subagent runs in its own context and returns only a summary. The required keys are name and description.
• Priority runs managed, --agents, .claude/agents/, ~/.claude/agents/, then plugins.
• Enforce read-only access with tools. In the default auto mode, permissionMode is ignored.
• Always set model. Without it, the subagent usually runs on the main conversation’s model.
• Broken YAML means the definition doesn’t load; misspelled keys are silently ignored. claude plugin validate catches only the first.
• Subagent requests count toward the same usage limits as the main conversation.