Claude Code: Agents Frontmatter Reference

Quick-reference tables for defining subagents in .claude/agents/*.md.

← Back to Claude Code Best Practice

Frontmatter Fields

Field	Type	Required	Description
`name`	string	Yes	Unique identifier using lowercase letters and hyphens
`description`	string	Yes	When to invoke. Use `"PROACTIVELY"` for auto-invocation by Claude
`tools`	string/list	No	Comma-separated allowlist of tools (e.g., `Read, Write, Edit, Bash`). Inherits all tools if omitted. Supports `Task(agent_type)` syntax to restrict spawnable subagents
`disallowedTools`	string/list	No	Tools to deny, removed from inherited or specified list
`model`	string	No	Model alias: `haiku`, `sonnet`, `opus`, or `inherit` (default: `inherit`)
`permissionMode`	string	No	Permission mode: `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, or `plan`
`maxTurns`	integer	No	Maximum number of agentic turns before the subagent stops
`skills`	list	No	Skill names to preload into agent context at startup (full content injected, not just made available)
`mcpServers`	list	No	MCP servers for this subagent — server name strings or inline `{name: config}` objects
`hooks`	object	No	Lifecycle hooks scoped to this subagent: `PreToolUse`, `PostToolUse`, `Stop` (converted to `SubagentStop` at runtime)
`memory`	string	No	Persistent memory scope: `user`, `project`, or `local`
`background`	boolean	No	Set to `true` to always run as a background task (default: `false`)
`isolation`	string	No	Set to `"worktree"` to run in a temporary git worktree (auto-cleaned if no changes)
`color`	string	No	CLI output color for visual distinction (e.g., `green`, `magenta`). Functional but absent from official frontmatter table — documented in interactive quickstart only

Memory Scopes

Scope	Storage Location	Shared	Version Controlled
`user`	`~/.claude/agent-memory/<name>/`	No	No
`project`	`.claude/agent-memory/<name>/`	Yes	Yes
`local`	`.claude/agent-memory-local/<name>/`	No	No

See claude-agent-memory.md for full details.

Invocation

Agents are invoked via the Task tool, never via bash commands:

Task(subagent_type="agent-name", description="...", prompt="...", model="haiku")

Other invocation and management methods:

Method	Description
`--agents '{...}'` CLI flag	Define session-scoped agents via JSON (accepts `description`, `prompt`, `tools`, `model`, etc.)
`claude agents` CLI command	List all configured agents grouped by source (added v2.1.51)
`/agents` interactive command	Create, edit, and manage agents interactively
Command delegation	A command file (`.claude/commands/`) can delegate to an agent
Agent resumption	Completed subagents can be resumed with their agent ID for follow-up work

Example: Minimal Agent

---
name: code-reviewer
description: Reviews code for quality issues
tools: Read, Grep, Glob
model: haiku
---

Review the code for quality issues and report findings.

Example: Full-Featured Agent (All Fields)

---
name: deploy-manager
description: Use this agent PROACTIVELY for deployment pipelines and release management
tools: Read, Write, Edit, Bash, Grep, Glob, Task(monitor, rollback)
disallowedTools: NotebookEdit
model: sonnet
permissionMode: acceptEdits
maxTurns: 25
skills:
  - deploy-checklist
  - rollback-procedures
mcpServers:
  - slack
  - name: pagerduty
    command: npx
    args: ["-y", "@pagerduty/mcp-server"]
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-deploy-command.sh"
  PostToolUse:
    - matcher: "Write"
      hooks:
        - type: command
          command: "./scripts/log-file-changes.sh"
  Stop:
    - hooks:
        - type: command
          command: "./scripts/notify-deploy-complete.sh"
memory: project
background: false
isolation: worktree
color: blue
---

You are a deployment manager. Follow the deploy-checklist skill for
pre-flight checks and use rollback-procedures if any step fails.
Notify the team via Slack when deployment completes.

Scope and Priority

When multiple subagents share the same name, the higher-priority location wins:

Location	Scope	Priority
`--agents` CLI flag	Current session	1 (highest)
`.claude/agents/`	Current project	2
`~/.claude/agents/`	All your projects	3
Plugin's `agents/` directory	Where plugin is enabled	4 (lowest)

5.3 KiB Raw Blame History