← All posts

How Do I Create a Custom Subagent in Claude Code?

A subagent is a helper Claude can hand a task to. It works in its own context window and reports back a summary. One Markdown file defines it.

November 17, 2026 7 min read Guide
Quick answer

Create a Markdown file in .claude/agents/ (this project) or ~/.claude/agents/ (all your projects). The YAML frontmatter needs a name and a description; optional fields such as tools and model restrict what it can use and which model it runs on. The body becomes the subagent's system prompt. Claude delegates on its own when a task matches the description, or you can call it by name ("use the code-reviewer subagent") or with an @-mention. Each subagent runs in its own context window, so only its final summary lands in your main conversation.

What does a subagent file look like?

This is the minimal example from the subagents docs:

---
name: code-reviewer
description: Reviews code for quality and best practices
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.

Save it as .claude/agents/code-reviewer.md. Claude Code watches these folders, so a new file usually works within seconds. A folder you create in the middle of a session needs a restart.

Where can subagent files live?

LocationScopePriority
Managed settingsOrganization1 (highest)
--agents flag (JSON)Current session2
.claude/agents/Current project3
~/.claude/agents/All your projects4
A plugin's agents/ folderWhere the plugin is enabled5

When two definitions share a name, the higher priority wins. The identity comes from the name field, not the file path, so moving a file into a subfolder does not rename it. Commit project subagents so the whole team gets them.

Which frontmatter fields matter most?

FieldUse it to
nameIdentify the subagent (required, no :)
descriptionTell Claude when to delegate (required)
tools / disallowedToolsAllow or deny specific tools, for example a read-only reviewer
modelPick sonnet, opus, haiku, fable, a full model ID or inherit
permissionModeRun in a mode such as plan or acceptEdits
maxTurns, skills, mcpServers, hooks, isolationCap turns, preload skills, scope MCP servers, add hooks, or run in a worktree

Field names are camelCase. Claude Code ignores fields it does not recognize without an error, so a typo such as maxturns fails silently. Check spelling when a setting seems to do nothing.

How does Claude decide to use a subagent?

Claude reads every subagent's description and delegates when a task matches. The docs suggest phrases such as "use proactively" in the description to encourage this. Keep descriptions short: Claude Code warns at startup if the combined descriptions of your custom subagents pass 15,000 tokens.

You can also call one directly:

What built-in subagents come with Claude Code?

To switch one off, add Agent(Explore) (or another name) to permissions.deny.

What does a subagent see, and what comes back?

A subagent does not see your conversation. It starts with its own system prompt, the delegation message Claude writes, your CLAUDE.md files (except for Explore, Plan and agents with omitClaudeMd), a git status snapshot and any preloaded skills. Only its final summary returns to the main conversation.

That isolation is the point. A test run with 3,000 lines of output, or a search across a large repository, stays in the subagent's window. Your main session gets the five lines that matter. Two caveats:

Can subagents run in the background or spawn other subagents?

Yes to both. Foreground subagents block until they finish and pass permission prompts to you. Background subagents run while you keep working, and their prompts appear in your session labeled with the subagent's name. Up to 20 can run at once by default.

Subagents can spawn their own subagents up to three levels below the main conversation. Set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 to turn nesting off.

Three subagents worth writing first

  1. A read-only reviewer with tools: Read, Glob, Grep that checks a diff against your conventions.
  2. A test runner that runs the suite, fixes failures and reports only what changed.
  3. A researcher on a smaller model that answers "where is X handled?" without filling your main context with file reads.

FAQ

What is the difference between a subagent and a skill?

A skill adds instructions to the current conversation when it is used. A subagent runs separately in its own context window and returns a summary. Use a skill for know-how, a subagent for work whose output you do not want in your main context.

Does the /agents command still create subagents?

In current versions /agents prints a reminder to ask Claude or edit the agents folders directly. Asking Claude to write the file is the quickest route.

Can a subagent edit files?

Yes, unless you limit its tools. Note that /rewind usually does not restore edits a subagent made, so use git for those.

Do subagents load my CLAUDE.md?

Custom subagents do by default. The built-in Explore and Plan agents, and any subagent with omitClaudeMd set, do not.

Sources

Checked against the official docs on November 17, 2026: Create custom subagents, Manage costs effectively and Checkpointing.

See every current command and shortcut in one reference.

Open the Claude Code Cheatsheet →