Claude Code Subagents: Setup, Frontmatter Reference and 7 Example Agents

Claude Code subagents are separate Claude workers that the main session hands a task to. Each one runs in its own context window, with its own system prompt, its own tool list and, if you want, its own model. It does the work, then sends back one summary, so the file dumps, test logs and search results stay out of your main conversation. You define a custom subagent as a Markdown file with YAML frontmatter in .claude/agents/ (one project) or ~/.claude/agents/ (all your projects). This guide covers how subagents work, the built-in ones, every frontmatter field, scopes and precedence, automatic vs explicit invocation, background and parallel runs, how subagents compare with skills and agent teams, and seven complete example agents you can paste. Everything was checked against the Claude Code docs in November 2026 (Claude Code v2.1.319).

What are Claude Code subagents?

The subagents docs describe them as specialized assistants for specific kinds of tasks. When Claude meets a task that matches a subagent's description, it writes a delegation message and starts that subagent through its Agent tool (called Task before v2.1.63; old Task(...) references still work as aliases). The subagent works on its own and returns a result.

Three things make a subagent different from just asking Claude in the main chat:

• Its own context window. A non-fork subagent starts fresh. It does not see your conversation, the files Claude already read, or skills you already ran. It sees its own system prompt, the task message Claude wrote, your CLAUDE.md files, a git status snapshot and any skills you preload.
• Its own tools and permissions. You can give a reviewer Read, Grep, Glob and nothing else. Claude Code enforces that list; it is not a polite request in a prompt.
• Its own prompt and model. The Markdown body of the file replaces the Claude Code system prompt for that subagent, and model can put it on Haiku, Sonnet, Opus or Fable.

Why use subagents?

Between them, the docs and Anthropic's own subagent article give four good reasons:

1. Keep noise out of your main context. A full test run, a wide grep or a 3,000-line log stays in the subagent's window. You get back "4 tests fail, here is why".
2. Run independent work in parallel. Three subagents researching the auth, database and API layers finish sooner than one session doing them in turn.
3. Enforce limits. A read-only reviewer or a SELECT-only database agent is safer than a prompt that says "please don't edit".
4. Spend less on simple jobs. Route file collection, link checking or log triage to model: haiku.

One correction to advice that still ranks well: the current best practices page lists "use subagents to protect your context window" and "delegate to a subagent for a better answer" as outdated habits. Most current models have a 1M-token window and compact on their own, and handing the same task to a subagent does not make the answer smarter. What does help is a fresh reviewer that never saw your reasoning. Use subagents for parallelism, noisy output, enforced limits and independent review, and expect each one to cost extra tokens.

Built-in subagents in Claude Code

Claude Code ships with these, and uses them without being asked:

Agent	Model	Tools	Used for
Explore	Main conversation's model (on Fable with a subscription or Console account, the opus alias)	Read-only; Write and Edit denied	File discovery and code search, at a "quick", "medium" or "very thorough" level
Plan	Inherits the main model	Read-only	Research while you are in plan mode
general-purpose	CLAUDE_CODE_SUBAGENT_MODEL if set, else main model	All tools available to subagents	Multi-step tasks that both explore and change code
claude	Follows the subagent model order	All tools available to subagents	Catch-all, and the default agent for background sessions
statusline-setup	Sonnet	Not documented	Runs when you use /statusline
claude-code-guide	Haiku	Not documented	Answers questions about Claude Code itself

Older posts say Explore runs on Haiku. That was true when Explore launched in v2.0.17; today it runs on the main conversation's model. To put exploration on a cheaper model, create your own subagent named Explore in .claude/agents/ with model: haiku. A user or project subagent with a built-in's name overrides the built-in.

Explore and Plan start without your CLAUDE.md files and the git status snapshot, to stay fast. Every other built-in and custom subagent loads both.

To turn built-ins off: deny one type with "Agent(Explore)" in permissions.deny, deny the whole Agent tool to stop all delegation, or set CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 to remove only Explore and Plan.

1. Jul 24, 2025v1.0.60: custom subagents launch with the /agents command.
2. Sep 29, 2025v2.0.0: the --agents flag adds subagents from JSON at launch.
3. Oct 15, 2025v2.0.17: the built-in Explore subagent arrives (on Haiku at the time).
4. Oct 27, 2025v2.0.28: the Plan subagent; Claude can resume subagents and pick their model.
5. Nov 17, 2025v2.0.43: skills frontmatter field and the SubagentStart hook event.
6. Jan 7, 2026v2.1.0: skills can run in a subagent with context: fork.
7. Feb 2026v2.1.33 adds memory and Agent(type) allowlists, v2.1.49 adds isolation: worktree, v2.1.63 renames the Task tool to Agent.
8. Jul 1, 2026v2.1.198: /agents stops opening the wizard and points you to the agent folders.
9. Oct 16, 2026v2.1.302: fork mode becomes the default in claude -p, the Agent SDK, VS Code and the desktop app, and VS Code and the desktop app always run subagents in the background, as the terminal does.

How to create a custom subagent

A subagent is one Markdown file. You can have Claude write it, or write it yourself.

Option 1: ask Claude to write it

In a session, describe the agent and where to save it:

Create a project subagent in .claude/agents/ called test-runner. It runs the
test suite, reports only failing tests with their errors, and fixes them if
the fix is obvious. Give it Read, Edit, Bash, Grep and Glob, and use Sonnet.

Claude writes .claude/agents/test-runner.md with a name, description, tools, model and a system prompt. Open the file and check the frontmatter before you rely on it.

What happened to the /agents wizard?

Many guides (and Anthropic's own course) tell you to run /agents and click through a wizard. On Claude Code v2.1.197 and earlier, /agents opened an interactive screen with a Running tab and a Library tab for creating, editing and deleting agents. From v2.1.198 (July 2026), /agents only prints a reminder to ask Claude or edit .claude/agents/ and ~/.claude/agents/ directly. To see subagents that are running now, use /tasks, which also shows each one's model.

Option 2: write the file by hand

Create .claude/agents/code-reviewer.md:

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

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

The frontmatter is the configuration. The body is the system prompt. Claude Code watches .claude/agents/ and ~/.claude/agents/ and picks up new or edited files within a few seconds, with no restart. Restart only when you create the very first file in an agents folder that did not exist when the session started, or when the folder came from --add-dir.

Option 3: pass agents as JSON with --agents

For a one-off session or a script, pass definitions on the command line. They are not 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"
  }
}'

prompt replaces the Markdown body. Every frontmatter field works here except color and experimental, which are ignored. In non-interactive mode (claude -p) the flag also accepts a path to a JSON file, from v2.1.281.

Subagent file format: every frontmatter field

Only name and description are required. Field names are camelCase and must match exactly. This is the full list from the frontmatter reference:

Field	What it does	Values / notes
name	Unique ID; hooks see it as agent_type	Up to 256 chars, no :, can't start with -. Filename doesn't have to match
description	When Claude should delegate to this agent	Keep it short; add "use proactively" to encourage auto-delegation
tools	Allowlist of tools	Comma string or YAML list. Omit to inherit all tools available to subagents. mcp__github__* gives one MCP server's tools
disallowedTools	Denylist, removed first	Write, Edit, mcp__github, or mcp__* for all MCP tools
model	Which model runs it	sonnet, opus, haiku, fable, a full ID like claude-opus-5-5, or inherit
permissionMode	Permission mode for the agent	default, acceptEdits, auto, dontAsk, bypassPermissions, plan (manual = default)
maxTurns	Cap on agentic turns	Output is marked partial at the cap; Claude can resume it
autoCompactWindow	Compact this agent earlier	Plain integer from 100000 to 1000000 (not 200k)
skills	Skills to preload in full at startup	Up to 32 names; can't preload skills with disable-model-invocation: true
mcpServers	MCP servers for this agent only	Name of a configured server, or an inline .mcp.json-style definition
hooks	Hooks that run only while this agent is active	Any hook event; Stop becomes SubagentStop
memory	Persistent memory folder across sessions	user, project or local
background	Always run in the background	true; subagents already start in the background by default
omitClaudeMd	Start without user, project and local CLAUDE.md	true; managed policy files still load
effort	Effort level while this agent runs	low, medium, high, xhigh, max (depends on the model)
isolation	Run in a temporary git worktree	worktree; cleaned up if the agent made no changes
color	Color in the task list and transcript	red, blue, green, yellow, purple, orange, pink, cyan
initialPrompt	First user turn when run as the main agent	Only with --agent or the agent setting
experimental	Experimental options map	cacheTtl: 5m or 1h for prompt cache lifetime

A few details that trip people up:

• tools vs disallowedTools. If you set both, the denylist is applied first, then the allowlist. A disallowedTools entry like Bash(git push *) removes the whole Bash tool. To block only some commands, add a Bash deny rule to permissions.deny in settings instead.
• Some tools never reach subagents. AskUserQuestion, EnterPlanMode, ScheduleWakeup and a few others are always removed. Background subagents (the default) also lose built-ins outside a short list that includes Read, Grep, Glob, Bash, Edit, Write, WebFetch, WebSearch, Skill and TodoWrite. MCP tools stay.
• permissionMode often doesn't apply. If your main session is in bypassPermissions, acceptEdits or auto mode, the subagent runs in that mode and ignores its own setting. In plan mode, it stays in plan mode.
• Plugin agents ignore hooks, mcpServers and permissionMode for security. Copy the file into .claude/agents/ if you need them.

Which model does a subagent use?

Claude Code picks the model in this order: the model Claude passes on that one call, then the agent's model field, then the CLAUDE_CODE_SUBAGENT_MODEL environment variable, then the main conversation's model. To force one model on every subagent, set both CLAUDE_CODE_SUBAGENT_MODEL and CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 in the env block of .claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

Subagents inherit your extended thinking setting. A subagent's context window comes from its own model, so a smaller model means a smaller window. For what each model costs per token, see Claude API prices.

Where subagent files live: scopes and precedence

When two subagents share a name, the higher-priority location wins:

Priority	Location	Scope	Notes
1 (highest)	Managed settings .claude/agents/	Whole organization	Deployed by admins
2	--agents JSON flag	Current session	Not saved to disk
3	.claude/agents/	Current project	Commit it so your team shares it
4	~/.claude/agents/	All your projects	Personal agents
5 (lowest)	A plugin's agents/ folder	Where the plugin is enabled	Named plugin-name:agent-name

Claude Code scans these folders recursively, so .claude/agents/review/security.md works. For project and user scopes the subfolder doesn't change the name; for plugins it does (my-plugin:review:security). Project agents are found by walking up from your working directory to the repo root, and the closest definition wins. Agents in a folder added with --add-dir load too.

How Claude picks a subagent (and how to force one)

Automatic delegation. Claude reads your request, the description of every subagent and the current context, then decides. That makes the description the most important line in the file. "Reviews staged changes for security issues before commits" routes better than "security expert". Phrases like "use proactively" or "use immediately after writing code" make Claude reach for it more often. All descriptions load into context at startup, and past 15,000 tokens combined Claude Code warns you, so keep them to a sentence or two and put the detail in the body, which loads only when the agent runs.

Explicit invocation has three levels:

1. Name it in your prompt: "Use the test-runner subagent to fix failing tests." Claude usually delegates, but it decides.
2. @-mention it: type @ and pick it from the list, or type @agent-code-reviewer (plugin agents: @agent-my-plugin:code-reviewer). This guarantees that agent runs.
3. Run the whole session as it: claude --agent code-reviewer, or "agent": "code-reviewer" in .claude/settings.json. The agent's prompt replaces the default system prompt and its tool limits and model apply to the main thread.

You can also tell Claude when to delegate in your CLAUDE.md, for example "always use the code-reviewer subagent before committing". See CLAUDE.md examples for how to word rules like that.

Running subagents in parallel and in the background

By default, a subagent Claude spawns from your main conversation starts in the background (in the terminal since v2.1.198, and in VS Code and the desktop app since v2.1.302). You keep typing while it works, its permission prompts show up in your main session with its name, and its report arrives as a notification in a later turn. /tasks lists running subagents; open one with Enter to read its transcript or send it a message.

To run work in parallel, just ask: "Research the authentication, database and API modules in parallel using separate subagents." Up to 20 can run at once by default (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS changes it). Subagents can also start their own subagents, up to three layers deep (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH).

If you want Claude to wait for a result before moving on, turn fork mode off with "CLAUDE_CODE_FORK_SUBAGENT": "0" in the env block of your settings, restart, and ask it to wait. Ctrl+B still sends a waiting subagent to the background.

To continue a finished subagent instead of starting over, say "continue that code review and now check the authorization logic". Claude resumes it with its full history using SendMessage. Explore and Plan are one-shot and can't be resumed.

Subagents vs skills vs slash commands vs agent teams

Claude Code has several ways to package work, and "Claude Code agents" can mean any of them. Here is how they differ:

Feature	Runs where	Context	Best for	Defined in
Subagent	Inside your session, separate window	Fresh, plus CLAUDE.md	Noisy, self-contained or parallel tasks; enforced tool limits	.claude/agents/*.md
Fork (/subtask)	Inside your session, background	Copy of your whole conversation	Side tasks that need everything you've discussed	Nothing to define
Skill	Your main conversation (or a subagent with context: fork)	Your conversation	Reusable instructions and workflows, /name commands	.claude/skills/<name>/SKILL.md
Slash command	Same as a skill	Your conversation	Same as skills; .claude/commands/ files were merged into skills and still work	.claude/commands/*.md
Agent team	Several full Claude Code sessions	Each teammate fully independent	Work where agents must talk to each other and share a task list	CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Background session	Separate session in agent view	Its own	Long jobs you monitor from claude agents	claude --bg

The two connect in both directions. A subagent can preload skills with skills:, and a skill with context: fork and agent: Explore runs its instructions inside a subagent. Agent teams are still experimental and, per the agent teams docs, "use significantly more tokens" than a single session. A teammate can reuse a subagent definition by name. Browse ready-made skills in the agent skills directory, and see Claude Code commands for the built-in slash commands.

Claude Code subagent examples you can paste

Seven complete agents. Save each as its own file under .claude/agents/ for one project or ~/.claude/agents/ for all of them. Each has the smallest tool list that does the job.

1. Code reviewer (read-only, remembers your conventions)

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews the current diff for bugs, security issues and readability. Use proactively after writing or modifying code and before committing.
tools: Read, Grep, Glob, Bash
model: sonnet
memory: project
color: blue
---

You are a senior code reviewer. You never edit files.

When invoked:
1. Run `git diff HEAD` (and `git diff --staged`) to see what changed.
2. Read the changed files and enough surrounding code to understand them.
3. Check your agent memory for conventions and recurring issues in this repo.

Review for, in this order:
- Correctness: logic errors, missed edge cases, broken error handling
- Security: injection, missing auth checks, secrets in code, unsafe input
- Tests: changed behavior without a test
- Readability: unclear names, duplicated code, dead code

Report findings grouped as Critical (must fix), Warnings (should fix) and
Suggestions. For each one give the file and line, the problem, and a concrete fix.
Only flag style issues if they hurt readability. If the diff is clean, say so.

After the review, save any new repo convention or recurring issue to your memory.

2. Test runner and fixer

.claude/agents/test-runner.md

---
name: test-runner
description: Runs the test suite, reports failing tests and fixes them. Use proactively after code changes or when the user mentions failing tests.
tools: Read, Edit, Bash, Grep, Glob
model: sonnet
color: green
---

You run tests and fix failures without changing what the tests check.

1. Find the test command (package.json scripts, Makefile, pytest.ini, go.mod).
2. Run the full suite once. Keep the output to yourself.
3. For each failing test, read the test and the code under test and decide:
   - the code is wrong: fix the code
   - the test is outdated because behavior changed on purpose: update the test
     and say so explicitly
4. Re-run only the failing tests until they pass, then run the full suite once more.

Never delete or skip a test to make it pass. Never weaken an assertion
without explaining why.

Return: the command you ran, passed/failed counts before and after, and
one line per fix (file, what changed, why).

3. Debugger

.claude/agents/debugger.md

---
name: debugger
description: Finds the root cause of errors, stack traces and unexpected behavior, then applies a minimal fix. Use when the user reports a bug or an error message.
tools: Read, Edit, Bash, Grep, Glob
model: opus
effort: high
color: red
---

You are an expert debugger focused on root causes, not symptoms.

1. Capture the exact error message, stack trace and steps to reproduce.
2. Reproduce the failure with a command or a small script.
3. Form hypotheses, then test them: read code, check `git log -p` for recent
   changes to the failing area, add temporary logging if needed.
4. Apply the smallest fix that addresses the root cause.
5. Re-run the reproduction to confirm the fix, and remove temporary logging.

Return:
- Root cause in one or two sentences
- Evidence (the line, log or test that proves it)
- The fix (files changed)
- How you verified it
- How to prevent it next time (a test, a type, a check)

4. Docs writer

.claude/agents/docs-writer.md

---
name: docs-writer
description: Writes and updates README files, API docs and code comments to match the current code. Use after adding a feature or changing a public API.
tools: Read, Write, Edit, Grep, Glob
model: sonnet
color: purple
---

You write developer documentation that matches the code exactly.

1. Read the code you are documenting. Never describe behavior you have not
   seen in the source.
2. Read the existing docs and keep their structure, tone and formatting.
3. Update or add: what it does, install/setup, a minimal working example,
   parameters or options with types and defaults, errors it can return.
4. Every code example must be complete and runnable as written.

Style: short sentences, active voice, second person. No marketing words.
Don't touch files outside docs/, README files and doc comments unless asked.

Return a list of the files you changed and one line on each change.

5. Security auditor

.claude/agents/security-auditor.md

---
name: security-auditor
description: Audits code and dependencies for security vulnerabilities. Use before a release, after auth or payment changes, or when the user asks for a security review.
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
model: opus
color: orange
---

You are an application security auditor. You report; you never change code.

Check, with file and line for every finding:
- Injection: SQL, shell, template, path traversal
- Auth: missing checks on routes, IDOR, weak session or token handling
- Secrets: keys, tokens or passwords in code, config or git history
- Input: missing validation on request bodies, uploads, redirects
- Crypto: weak hashing, home-made crypto, disabled TLS verification
- Dependencies: run the project's audit command (npm audit, pip-audit,
  cargo audit, govulncheck) if it is available

Rate each finding Critical, High, Medium or Low, explain how it could be
exploited in one sentence, and give the fix. Do not report theoretical issues
you cannot point to in the code. If you find nothing, say what you checked.

6. Database analyst (read-only SQL)

The prompt says "read only", but a hook makes it true. .claude/agents/db-analyst.md:

---
name: db-analyst
description: Answers questions about the data with read-only SQL queries. Use for data analysis, reports and checking what is in the database.
tools: Bash, Read
model: sonnet
color: cyan
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a data analyst with read-only access. Connect with
`psql "$DATABASE_READONLY_URL"` and run SELECT queries only.

1. List the relevant tables and columns first (\d, information_schema).
2. Write efficient queries: filter early, add LIMIT while exploring.
3. Explain the approach, show the final query, then the results as a table.
4. State assumptions and anything that looks like a data quality problem.

If asked to INSERT, UPDATE, DELETE or change the schema, refuse and explain
that you only have read access.

And the hook script, scripts/validate-readonly-query.sh (run chmod +x on it). It reads the hook's JSON from stdin and exits with code 2 to block a write:

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
[ -z "$COMMAND" ] && exit 0

if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE|GRANT)\b' > /dev/null; then
  echo "Blocked: write operations are not allowed. Use SELECT queries only." >&2
  exit 2
fi
exit 0

7. Codebase researcher (cheap and fast)

~/.claude/agents/researcher.md (user scope, useful in every repo):

---
name: researcher
description: Finds where and how something is implemented in the codebase and answers with file paths. Use for "where is", "how does X work" and "what calls Y" questions.
tools: Read, Grep, Glob, WebFetch
model: haiku
color: yellow
---

You are a fast codebase researcher. You never edit files.

1. Search broadly with Grep and Glob, then read only the relevant parts.
2. Follow the call chain until you can answer the question.
3. Use WebFetch only for official library docs when the code depends on them.

Answer in under 250 words:
- A direct answer in one or two sentences
- The key files as path:line with one line on what each does
- Anything surprising or risky you noticed

Do not paste large code blocks. Quote at most a few lines when it matters.

Best practices and common pitfalls

Write descriptions that route. The description decides when the agent runs. Say when to use it ("after modifying code", "when tests fail"), not just what it is. If Claude never picks your agent, the description is too vague or overlaps another agent's. Most teams end up with a handful of focused agents, not thirty.

Give the fewest tools that work. If you omit tools, the agent inherits everything, including every MCP tool. A reviewer needs Read, Grep, Glob and maybe Bash for git diff. Only give Edit and Write to agents whose job is to change files. Leave Agent out of tools if the agent shouldn't spawn agents of its own.

Pass context on purpose. A non-fork subagent can't see your conversation. If a rule matters ("ignore vendor/", "we use pnpm"), put it in CLAUDE.md, the agent body, or ask Claude to include it when delegating. If the task depends on a long discussion, use a fork instead.

Ask for short, structured reports. Twenty parallel subagents that each return 2,000 words will fill your context anyway. Every example above ends with a "Return:" section for that reason.

Watch the cost. Each subagent sends its own requests against the same plan limits or API bill, and a fresh one spends tokens re-reading files your session already had. Put simple jobs on model: haiku, check /usage to see what each subagent type costs, and don't spawn one subagent per file for a job one session could do in a single pass. See Claude Code pricing for plan limits, or estimate prompt sizes with the token counter.

Don't let parallel agents edit the same files. Two subagents changing one file is a merge conflict waiting to happen. Give each a separate area, or set isolation: worktree so each works in its own git worktree.

Check what loaded. If an agent doesn't show up in the @ list, look for a missing name or description, YAML errors, or a misspelled field with claude --debug. Use /tasks to confirm the model a subagent is running on.

Commit project agents. .claude/agents/ belongs in version control so your whole team gets the same reviewer and test runner. For more on setting up Claude Code overall, see how to use Claude Code, and compare it with other tools in our AI coding agents roundup.

FAQ

What is a subagent in Claude Code?

A subagent is a separate Claude instance that your main Claude Code session starts for one task. It has its own context window, system prompt, tool list and optional model, and it returns only a final summary. You define custom ones as Markdown files in .claude/agents/ or ~/.claude/agents/.

Why use subagents in Claude Code?

Use them to keep noisy output like test runs and wide searches out of your main conversation, to run independent tasks in parallel, to enforce tool limits such as a read-only reviewer, and to run simple jobs on a cheaper model. They don't make answers smarter on their own and each one costs extra tokens.

Can Claude Code run subagents in parallel?

Yes. Subagents start in the background by default, and Claude can run up to 20 at once in a session. Ask for it directly, for example "research these three modules in parallel using separate subagents".

How do I see the list of Claude Code subagents?

Your custom agents are the files in .claude/agents/ and ~/.claude/agents/, and typing @ in a session lists them along with plugin agents. Running subagents appear in /tasks. Since v2.1.198, /agents only points you to those folders instead of opening a manager.

What is the difference between Claude Code subagents and skills?

A skill is a set of instructions that loads into your main conversation when invoked, and it can also be a /command. A subagent runs in a separate context window with its own tools and model and returns a summary. You can combine them: preload skills into a subagent with skills:, or run a skill in a subagent with context: fork.

Do subagents read CLAUDE.md?

Custom subagents and general-purpose load your CLAUDE.md files and a git status snapshot. The built-in Explore and Plan agents skip both, and a custom agent with omitClaudeMd: true skips your user, project and local CLAUDE.md files.

What is the difference between subagents and agent teams?

Subagents work inside one session and report back to the main agent. Agent teams are several full Claude Code sessions that message each other and share a task list. Teams are experimental, need CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, and use many more tokens.