Agent Skills: Claude Code Subagents — 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.

| Agent | Model | Tools | Purpose | |:------|:------|:------|:--------| | Explore | Haiku (fast) | Read-only | File discovery, code search, codebase exploration. Thoroughness: quick / medium / very thorough | | Plan | Inherits | Read-only | Codebase research during plan mode | | general-purpose | Inherits | All | Complex multi-step tasks requiring both exploration and modification | | statusline-setup | Sonnet | — | Invoked automatically for /statusline | | claude-code-guide | Haiku | — | Invoked automatically for Claude Code questions |

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.

| Location | Scope | Priority | |:---------|:------|:---------| | Managed settings | Organization-wide | 1 (highest) | | --agents CLI flag | Current session only | 2 | | .claude/agents/ | Current project | 3 | | ~/.claude/agents/ | All your projects | 4 | | Plugin agents/ directory | Where plugin is enabled | 5 (lowest) |

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.

| Field | Required | Description | |:------|:---------|:------------| | name | Yes | Unique identifier: lowercase letters and hyphens, max 64 chars. Hooks receive this as agent_type. Filename need not match | | description | Yes | When Claude should delegate to this subagent. Write clearly — Claude uses this for routing. Include "use proactively" to encourage automatic delegation | | tools | No | Allowlist of tools the subagent can use. Inherits all tools when omitted. Use Agent(worker, researcher) syntax to restrict which subagent types can be spawned. See ./references/tool-and-permission-control.md | | disallowedTools | No | Denylist — removed from inherited or specified list. When both fields set, disallowedTools applied first | | model | No | Model to use: sonnet, opus, haiku, a full model ID (e.g., claude-opus-4-7), or inherit. Defaults to inherit. See ./references/model-and-effort.md | | permissionMode | No | Permission mode: default, acceptEdits, auto, dontAsk, bypassPermissions, or plan. Silently ignored for plugin subagents. See ./references/tool-and-permission-control.md | | maxTurns | No | Maximum agentic turns before the subagent stops | | skills | No | Skills to preload into the subagent's context at startup. Full skill content is injected (not just the description). Cannot preload skills with disable-model-invocation: true. See /claude-skills-overview-2026 for skill authoring | | mcpServers | No | MCP servers available to this subagent. Each entry: a server name string (reuses parent connection) or an inline definition. Silently ignored for plugin subagents. Inline servers connect when the subagent starts and disconnect when it finishes | | hooks | No | Lifecycle hooks scoped to this subagent. Silently ignored for plugin subagents. Stop hooks are auto-converted to SubagentStop at runtime. See ./references/hooks-for-subagents.md | | memory | No | Persistent memory scope: user, project, or local. Enables cross-session learning. See ./references/memory-and-context.md | | background | No | Set true to always run this subagent as a background task. Default: false | | effort | No | Effort level override when this subagent is active: low, medium, high, xhigh, max. Overrides session level but not CLAUDE_CODE_EFFORT_LEVEL env var. See ./references/model-and-effort.md | | isolation | No | Set worktree to run the subagent in a temporary git worktree (isolated repo copy). Auto-cleaned up if no changes made. Supported in plugin subagents. See ./references/memory-and-context.md | | color | No | Display color in task list: red, blue, green, yellow, purple, orange, pink, or cyan | | initialPrompt | No | Auto-submitted as the first user turn when this agent runs as the main session via --agent or the agent setting. Commands and skills are processed. Prepended to any user-provided prompt |

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)

| Variable | Purpose | |:---------|:--------| | CLAUDE_CODE_SUBAGENT_MODEL | Override model for ALL subagents. Overrides per-invocation parameter and frontmatter model. Set to inherit to use normal resolution | | CLAUDE_CODE_FORK_SUBAGENT=1 | Enable fork mode (v2.1.117+). See ./references/fork-mode.md | | CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 | Enable agent teams (v2.1.32+). See ./references/agent-teams.md | | CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 | Disable all background task functionality | | CLAUDE_AUTOCOMPACT_PCT_OVERRIDE | % of context capacity at which auto-compaction triggers (default ~95%) | | TASK_MAX_OUTPUT_LENGTH | Max characters in subagent output before truncation (default 32000, max 160000) | | CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 | Disable all built-in subagent types (non-interactive mode only) |

Reference files

| Topic | File | |:------|:-----| | Tool allowlist/denylist, Agent() spawn restrictions, permission modes | ./references/tool-and-permission-control.md | | Model aliases, CLAUDE_CODE_SUBAGENT_MODEL, effort levels | ./references/model-and-effort.md | | Hooks in frontmatter vs settings.json, SubagentStart/Stop schemas | ./references/hooks-for-subagents.md | | Memory scopes, what loads at startup, worktrees, compaction, resume | ./references/memory-and-context.md | | Fork mode (experimental, v2.1.117+) | ./references/fork-mode.md | | Agent teams vs subagents, enabling, best practices | ./references/agent-teams.md | | Full example subagent definitions with hook scripts | ./references/example-subagents.md |