Claude Code subagents are a good fit for repeatable side jobs that would otherwise fill the main conversation with search output, test logs or file-by-file notes. A subagent gets its own context window, system prompt, tool set and permissions, then returns a result to the parent session. It is still part of the same Claude Code session and its requests count against the same usage limits.

Docs checked: Anthropic’s Claude Code documentation on October 18, 2026. The fields and version notes below reflect the live docs on that date, not a local product test.

On this page

Start with the scope, not the prompt

A custom subagent is a Markdown file with YAML frontmatter. Where that file lives determines who can use it:

Location Scope Precedence
Managed settings Organization Highest
--agents Current launch only 2
.claude/agents/ Current project 3
~/.claude/agents/ All your projects 4
A plugin’s agents/ directory Wherever the plugin is enabled Lowest

For a repository-specific reviewer, put the file under .claude/agents/ and commit it with the project. For a personal helper you want everywhere, use ~/.claude/agents/. Claude Code scans those two folders recursively, so subfolders can keep a large collection tidy.

Precedence matters when two definitions share a name. A project definition overrides a user definition, while a managed definition overrides both. Within nested project directories, the definition closest to the working directory wins.

A minimal subagent file

Only name and description are required. The body after the closing --- is the subagent’s system prompt.

---
name: test-triage
description: Investigates failing tests and reports the smallest likely cause. Use after a CI or local test failure.
tools: Read, Grep, Glob, Bash
model: sonnet
maxTurns: 12
---

Trace the failure from the first meaningful error.
Do not edit files. Report:
1. the failing command or test,
2. the most likely cause,
3. evidence from the repository,
4. the smallest next action.

Keep the description short and operational. Claude uses it, along with the current request and conversation, to decide whether to delegate. Put detailed rules in the prompt body because that body loads only when the subagent runs.

Frontmatter names are exact and use camelCase. A misspelling such as maxturns is not a harmless style difference: Claude Code can ignore an unrecognized field. With current releases, claude --debug records likely misspellings in the session debug log.

Choose tools as a capability boundary

If you omit tools, the subagent inherits the tools available to subagents in the current session. A narrower allowlist is usually easier to reason about:

tools:
  - Read
  - Grep
  - Glob

That creates a read-oriented worker for code search and review. Add Bash only when the job needs commands. Add Edit or Write only when the worker is supposed to change files.

disallowedTools removes tools from either an inherited or explicit list. This is useful when a broad base configuration is convenient but one agent must not write:

disallowedTools: Edit, Write

Tool access and approval policy are separate. The optional permissionMode field can be default, acceptEdits, auto, dontAsk, bypassPermissions, plan, or manual as an alias for default. Project policy and managed restrictions still apply. Avoid treating a permissive mode as a replacement for a tight tool list.

Background execution also changes the effective built-in tool set. Claude Code retains a documented subset for background subagents and removes other built-ins even if the file lists them. The safe assumption is that the resolved tool pool can be narrower than the frontmatter suggests.

For broader isolation, set isolation: worktree. Claude Code then runs the subagent in a temporary Git worktree, branched by default from the repository’s default branch. It cleans up a worktree automatically when the subagent makes no changes.

Pick a model deliberately

The model field accepts a family alias such as sonnet, opus, haiku or fable, a full model ID, or inherit.

model: haiku

A small, bounded lookup may suit a faster model. A complex review that must reconcile several files may justify a larger one. inherit tracks the main conversation’s model instead of pinning a separate choice.

Claude Code resolves a custom subagent’s model in this order:

  1. a per-invocation model supplied when the subagent starts;
  2. the definition’s model field;
  3. CLAUDE_CODE_SUBAGENT_MODEL, if set;
  4. the main conversation’s model.

A model allowlist or provider limitation can still force a fallback. If the subagent inherits the session model, switching the session with /model also changes the model used by later inherited subagents.

maxTurns is a useful second limit. When the worker reaches it, Claude Code returns partial output rather than running indefinitely, and the parent can resume the same subagent if more work is justified.

Preload the right context

A subagent starts with its own context, not a copy of the parent transcript. Custom subagents normally receive the applicable CLAUDE.md files and Git status snapshot. Set omitClaudeMd: true when the delegation prompt and agent file contain everything the worker needs.

The skills field preloads complete skills at startup:

skills:
  - api-style
  - test-conventions

This differs from merely letting the subagent invoke the Skill tool later. Preloading puts the full skill content into its initial context. It is useful when every run must follow the same house rules, but it also consumes context, so do not preload unrelated references.

You can also scope MCP access with mcpServers. A string entry reuses an MCP server already configured in the parent session. An inline entry connects only while that subagent runs. Inline servers from project agent files require the relevant folder trust, and managed MCP policies still apply.

Persistent learning is opt-in through memory: user, project or local. Use it only when cross-session notes are genuinely useful. A deterministic reviewer may be better without memory; a project research agent may benefit from a project-scoped record of conventions already discovered.

Make delegation predictable

Automatic delegation is driven mainly by the request, the subagent’s description, and the current context. A vague description such as “helps with code” competes poorly with built-in agents and other custom definitions. Name the trigger and the expected job:

description: Reviews database migrations for locking, rollback and data-loss risks. Use before merging schema changes.

There are three practical ways to invoke a subagent:

  • Name it in ordinary language: “Use the migration-reviewer subagent on this diff.”
  • Use an agent @-mention to guarantee that specific agent runs for one task.
  • Launch the whole session with --agent or the agent setting.

Claude Code can also delegate automatically when the description matches. If you need the worker every time, explicit invocation is clearer than hoping the router infers your intent.

Define temporary subagents with --agents

The --agents flag accepts a JSON object of subagent definitions. These definitions exist only for that launch, so they work well for CI jobs, experiments and scripts that should not write files into a repository.

claude --agents '{
  "reviewer": {
    "description": "Reviews changed code and reports correctness risks",
    "prompt": "Inspect the diff. Do not edit files. Cite the relevant paths.",
    "tools": ["Read", "Grep", "Glob"],
    "model": "sonnet"
  }
}'

Claude Code validates the value at startup and exits when the configuration is invalid. In print mode, current releases can also accept a path to a JSON file. Unlike Markdown agent files, CLI definitions put the system instructions in a prompt field.

Use the CLI form for ephemeral automation. Use a project file when the definition belongs to the codebase and should be reviewed like other repository configuration.

Three patterns that work well

1. High-volume research

Give a read-only subagent repository search tools and ask it for a bounded summary. The main conversation receives the conclusion without carrying every grep result or file excerpt. This is the clearest win for context isolation.

2. Focused verification

A test-triage or migration-review agent can have a narrow prompt, limited tools and a turn cap. It returns evidence and a decision-shaped report while leaving implementation to the main conversation.

3. Independent implementation

For a well-bounded edit, a worktree-isolated subagent can make changes without sharing the parent’s working tree. This reduces collisions, but the parent still needs to inspect the result. Isolation is not review.

Common failure modes

The agent never runs. Tighten the description, name it explicitly, or use an @-mention. Restart Claude Code if the agents directory itself was created after the current session started.

The file is skipped. Check that the first line is ---, the YAML parses, and both name and description exist. A name cannot start with -, contain :, or exceed the documented limit.

The agent has too much power. Replace an inherited tool pool with a short tools list. Keep write tools out of research and review agents.

The result is too broad. State the output contract in the prompt body: what to inspect, what not to change, how to cite evidence, and when to stop.

The main conversation still becomes noisy. Ask for a summary and decision, not a replay of the subagent’s transcript. The value is the boundary between exploratory work and the result the parent actually needs.