Claude Subagent Reference

SOURCE: https://code.claude.com/docs/en/sub-agents.md (accessed 2026-05-28)

Claude Code Subagents — Reference

Subagents are specialized AI assistants that run in their own context window with custom system prompts, specific tool access, and independent permissions. Use one when a task would flood your main conversation with output you won't reference again; the subagent does the work in its own context and returns only a summary.

Subagents help you:

• Preserve context by keeping exploration and implementation out of your main conversation
• Enforce constraints by limiting which tools a subagent can use
• Reuse configurations across projects with user-level subagents
• Control costs by routing tasks to faster, cheaper models like Haiku

Subagents cannot spawn other subagents. For coordinated parallel work with inter-agent messaging, see ./references/agent-teams.md.

Built-in subagents

SOURCE: https://code.claude.com/docs/en/sub-agents.md § Built-in subagents (accessed 2026-05-28)

Claude Code includes built-in subagents. Explore and Plan skip CLAUDE.md files and the parent session's git status for speed. Every other built-in and custom subagent loads both.

Explore limitation: Haiku-based, read-only retrieval only. Do not delegate reasoning or analysis to Explore — validated ~50% accuracy on ambiguous queries. Use general-purpose for any task requiring interpretation.

Scope and file locations

SOURCE: https://code.claude.com/docs/en/sub-agents.md § Choose the subagent scope (accessed 2026-05-28)

Subagent files are Markdown files with YAML frontmatter. When multiple subagents share the same name, the higher-priority location wins.

Project subagents (.claude/agents/) are scanned recursively — subdirectories are allowed but do not affect the agent's name (identity comes only from the name frontmatter field). Keep name values unique across the whole tree.

Plugin subagents use scoped identifiers: agents/review/security.md in plugin my-plugin registers as my-plugin:review:security.

For plugin subagent security restrictions (hooks, mcpServers, permissionMode are silently ignored in plugin agents), see /claude-plugins-reference-2026.

Subagents load at session start. If you add or edit a subagent file directly on disk, restart your session to load it. Subagents created through the /agents interface take effect immediately.

Frontmatter fields

SOURCE: https://code.claude.com/docs/en/sub-agents.md § Supported frontmatter fields (accessed 2026-05-28)

Only name and description are required. All other fields are optional.

Tools not available in subagents

SOURCE: https://code.claude.com/docs/en/sub-agents.md § Available tools (accessed 2026-05-28)

These tools are unavailable to subagents even when listed in the tools field (they depend on the main conversation's UI or session state):

• Agent
• AskUserQuestion
• EnterPlanMode
• ExitPlanMode (unless permissionMode: plan)
• ScheduleWakeup
• WaitForMcpServers

Minimal example

---
name: code-reviewer
description: Expert code reviewer. 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.

When invoked, run git diff to see recent changes, focus on modified files, and begin review immediately.

Provide feedback organized by priority: Critical issues (must fix), Warnings (should fix), Suggestions (consider improving).

Invocation patterns

SOURCE: https://code.claude.com/docs/en/sub-agents.md § Invoke subagents explicitly (accessed 2026-05-28)

Three patterns in escalating strength:

Natural language — Claude decides whether to delegate:

Use the test-runner subagent to fix failing tests

@-mention — guarantees this specific subagent runs for one task (type @ and pick from typeahead, or type manually):

@"code-reviewer (agent)" look at the auth changes

For plugin subagents, type @agent- followed by the scoped name, for example @agent- + my-plugin:code-reviewer.

Session-wide — entire session uses this subagent's system prompt, tool restrictions, and model:

claude --agent code-reviewer

For plugin subagents with name conflicts, use the scoped name: claude --agent my-plugin:security-reviewer

Set as project default in .claude/settings.json:

{ "agent": "code-reviewer" }

The --agent CLI flag overrides the agent setting when both are present.

CLI-defined subagents

SOURCE: https://code.claude.com/docs/en/sub-agents.md § Choose the subagent scope (accessed 2026-05-28)

Define subagents in JSON at launch — exist only for that session:

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

The --agents flag accepts the same fields as file-based frontmatter. Use prompt for the system prompt (equivalent to the markdown body in file-based subagents).

Key environment variables

SOURCE: https://code.claude.com/docs/en/env-vars.md (accessed 2026-05-28)

Reference files