# Agent Frontmatter Reference

Complete reference for all agent .md YAML frontmatter fields, based on official Claude Code documentation.

Source: https://code.claude.com/docs/en/sub-agents

## Required Fields

### `name`
- **Type:** string
- **Required:** YES
- **Purpose:** Unique identifier for the agent. Used in `subagent_type` parameter of Task tool.
- **Examples:**
  ```yaml
  name: code-reviewer
  name: test-runner
  name: db-migration
  ```

### `description`
- **Type:** string (multi-line supported)
- **Required:** YES
- **Purpose:** Claude uses this to decide when to delegate tasks to this agent. Must be clear and specific.
- **Examples:**
  ```yaml
  description: Expert code reviewer for PR analysis. Use when reviewing code changes for security, logic, clean code, or feature-specific behavior.

  description: |
    Fast agent specialized for exploring codebases.
    Use this when you need to quickly find files by patterns,
    search code for keywords, or answer questions about the codebase.
  ```

## Optional Fields

### `model`
- **Type:** string
- **Default:** inherit (uses parent's model)
- **Valid values:** haiku, sonnet, opus, inherit
- **Guidance:**

| Model | Best for | Cost | Speed |
|-------|----------|------|-------|
| `haiku` | Simple tasks, search, scan | Lowest | Fastest |
| `sonnet` | Most tasks, code generation | Medium | Medium |
| `opus` | Complex reasoning, planning | Highest | Slowest |
| `inherit` | When you don't want to override | Parent's | Parent's |

- **Example:**
  ```yaml
  model: haiku
  ```

### `tools`
- **Type:** string (comma-separated)
- **Default:** all tools inherited
- **Purpose:** Whitelist of tools this agent can use. If specified, ONLY these tools are available.
- **Example:**
  ```yaml
  tools: "Read, Grep, Glob, Bash"
  ```

### `disallowedTools`
- **Type:** string (comma-separated)
- **Default:** none
- **Purpose:** Blacklist of tools to remove from the agent's available tools.
- **Example:**
  ```yaml
  disallowedTools: "Write, Edit, Bash"
  ```

### `permissionMode`
- **Type:** string
- **Default:** default
- **Valid values:** default, acceptEdits, dontAsk, bypassPermissions, plan
- **Details:**

| Mode | Behavior | Risk Level |
|------|----------|------------|
| `default` | Standard permission prompts | Low |
| `acceptEdits` | Auto-accept file edit permissions | Medium |
| `dontAsk` | Auto-deny all permission prompts | Medium |
| `bypassPermissions` | Skip ALL permission checks | **HIGH** |
| `plan` | Read-only, no modifications | None |

- **Example:**
  ```yaml
  permissionMode: acceptEdits
  ```

### `skills`
- **Type:** list of strings
- **Default:** none
- **Purpose:** Skills to preload into the agent's context at startup. Full skill content is injected.
- **Example:**
  ```yaml
  skills:
    - review-code
    - validate
  ```

### `hooks`
- **Type:** object
- **Default:** none
- **Purpose:** Lifecycle hooks scoped to this agent only.
- **Example:**
  ```yaml
  hooks:
    PreToolUse:
      - matcher: "Bash"
        hooks:
          - type: command
            command: "./scripts/validate-command.sh"
  ```

### `color`
- **Type:** string
- **Default:** none
- **Purpose:** Visual indicator color (displayed in some UI contexts).
- **Examples:** blue, yellow, purple, green, red, orange

## Available Tools

Tools that can be referenced in `tools` or `disallowedTools`:

### Core Tools
| Tool | Purpose |
|------|---------|
| `Read` | Read file contents |
| `Write` | Create/overwrite files |
| `Edit` | Edit existing files (find-and-replace) |
| `Bash` | Execute shell commands |
| `Glob` | Find files by pattern |
| `Grep` | Search file contents |

### Communication Tools
| Tool | Purpose |
|------|---------|
| `AskUserQuestion` | Ask user interactive questions |
| `TodoWrite` | Manage task lists |

### Agent Tools
| Tool | Purpose |
|------|---------|
| `Task` | Launch sub-agents |
| `Skill` | Invoke skills |
| `ToolSearch` | Discover deferred tools |

### Web Tools
| Tool | Purpose |
|------|---------|
| `WebFetch` | Fetch URL content |
| `WebSearch` | Search the web |

### Specialized Tools
| Tool | Purpose |
|------|---------|
| `NotebookEdit` | Edit Jupyter notebooks |

### MCP Tools
| Tool | Purpose |
|------|---------|
| `mcp__*` | Any MCP server tool (e.g., `mcp__smartstack__validate_conventions`) |

## Priority & Scope

Agents are loaded in priority order (higher overrides lower):

| Location | Priority | Scope |
|----------|----------|-------|
| `--agents` CLI flag | 1 (highest) | Session only |
| `.claude/agents/` | 2 | Project |
| `~/.claude/agents/` | 3 | User |
| Plugin agents | 4 (lowest) | Plugin |

## Examples

### Minimal Agent
```yaml
---
name: my-helper
description: Helps with basic tasks
---

You are a helpful assistant.
```

### Read-Only Explorer
```yaml
---
name: codebase-explorer
description: Fast codebase search and analysis
model: haiku
tools: "Read, Grep, Glob"
permissionMode: plan
---
```

### Full-Featured Agent
```yaml
---
name: feature-builder
description: |
  Builds complete features with tests.
  Use when implementing new features from requirements.
model: sonnet
tools: "Read, Write, Edit, Bash, Grep, Glob"
permissionMode: acceptEdits
skills:
  - validate
color: green
---
```
