---
topic: claude-code-agents
source_keys:
  - claude-code-docs-subagents
  - claude-code-docs-plugins
---

## Overview

Claude Code agents (called subagents) are Markdown files with YAML frontmatter stored in one of several scoped locations. Each runs in its own context window with a custom system prompt, specific tool access, and independent permissions. The parent conversation delegates to a subagent when its `description` matches the task.

## File format

```markdown
---
name: code-reviewer
description: Reviews code for correctness, security, and maintainability. Use proactively after code changes.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior code reviewer. Review for:
1. Correctness: logic errors, edge cases
2. Security: injection, auth bypass
3. Maintainability: naming, complexity
```

The body becomes the subagent's system prompt. Subagents receive only this system prompt plus basic environment details (working directory) — not the full Claude Code system prompt and not the parent conversation history.

## Supported frontmatter fields

Only `name` and `description` are required. All others are optional.

| Field | Description |
|---|---|
| `name` | Unique identifier: lowercase letters and hyphens. Used as `agent_type` in hooks. Filename does not have to match. |
| `description` | When Claude should delegate to this subagent — determines automatic routing. Write imperatively. |
| `tools` | Allowlist of tools the subagent can use. Inherits all tools if omitted. Comma-separated or array. Use `Agent(type1, type2)` syntax to restrict which subagents this agent can spawn. |
| `disallowedTools` | Denylist — removed from inherited or specified list. If both `tools` and `disallowedTools` are set, denylist is applied first. Supports `mcp__<server>` patterns. |
| `model` | Model alias (`sonnet`, `opus`, `haiku`, `fable`) or full ID (`claude-opus-4-8`). Defaults to `inherit` (parent model). |
| `permissionMode` | `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`. Inherited from parent; parent's mode takes precedence if stricter. **Ignored for plugin agents.** |
| `maxTurns` | Maximum agentic turns before the subagent stops. |
| `skills` | Skills to preload into the subagent's context at startup (full skill content injected, not just description). |
| `mcpServers` | MCP servers scoped to this subagent. Inline definitions connect on start, disconnect on finish. String references reuse the parent session's connection. **Ignored for plugin agents.** |
| `hooks` | Lifecycle hooks scoped to this subagent. **Ignored for plugin agents.** |
| `memory` | Persistent memory scope: `user`, `project`, or `local`. Enables cross-session learning. |
| `background` | `true` to always run as a background task. Default: `false`. |
| `effort` | Reasoning effort: `low`, `medium`, `high`, `xhigh`, `max`. Overrides session effort level. |
| `isolation` | `worktree` — runs in a temporary git worktree (isolated repo copy). Auto-cleaned up if no changes. |
| `color` | Display color in the task list: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. |
| `initialPrompt` | Auto-submitted as the first user turn when this agent runs as the main session agent (via `--agent`). |

## Storage locations and scope priority

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

When the same `name` is defined in multiple locations, the highest-priority location wins. Claude Code scans both `.claude/agents/` and `~/.claude/agents/` recursively — files can be organized into subfolders. Identity comes from the `name` frontmatter, not the filename.

## Plugin agent constraints

Plugin agents (in a plugin's `agents/` directory) have three fields ignored for security reasons:
- `hooks` — ignored
- `mcpServers` — ignored
- `permissionMode` — ignored

If any of these are needed, copy the agent file to `.claude/agents/` or `~/.claude/agents/` instead.

Plugin agents in subfolders get a scoped identifier: `plugin-name:subfolder:agent-name` (e.g., a file at `agents/review/security.md` in plugin `my-plugin` registers as `my-plugin:review:security`).

## Repo-specific placement (this repo)

Per ADR-0010, two categories of agent definitions exist in this repo:

- **Subagent definitions** (isolated context, separate context window): live in `core/agents/` — deployed to `~/.claude/agents/` by `install.sh`. These are the "true" subagents.
- **Plugin agents**: live in `plugins/<name>/agents/<name>.md`. Installed with the plugin.
- **Role skills** (inline mode switches, NOT agents): live in `.agents/skills/` with `category: roles`.

Never put role skills in `core/agents/`. Never put subagent definitions in `.agents/skills/`. The distinction is the isolation boundary — subagents get a fresh context window; role skills load inline.

## Model routing guidance (from factory §9)

- `haiku` — formatting, classification, fast lookups
- `sonnet` — most coding, review, analysis
- `opus` — adversarial reasoning, complex multi-step, security-critical
- Omit `model` to inherit from the parent session