Claude Code Agent Format Reference

Complete reference for .claude/agents/*.md agent definition files.

File Locations

Priority: CLI flag > project-level > user-level > plugin-provided.

File Structure

Each agent is a single Markdown file with YAML frontmatter:

---
# Required fields
name: agent-name
description: When and why the parent agent should delegate to this agent.

# Tool access (optional — inherits all if omitted)
tools: Read, Glob, Grep, Bash
disallowedTools: Write, Edit

# Execution settings (optional)
model: sonnet
permissionMode: default
maxTurns: 25

# Advanced (optional)
skills:
  - skill-name
mcpServers:
  server-name:
    command: node
    args: ["server.js"]
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate.sh"
memory: project
---

System prompt body goes here. This is what the agent sees as its instructions.

All Frontmatter Fields

Required

Tool Access

Use tools (allowlist) when the agent needs a small, specific set. Use disallowedTools (denylist) when the agent needs most tools but should be blocked from a few.

Available tool names: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task, NotebookEdit, AskUserQuestion.

To restrict which subagents can be spawned: Task(explorer, implementer) — only allows spawning agents named explorer or implementer.

Execution Settings

Permission Modes

Advanced

Full Examples

Read-Only Security Reviewer

---
name: security-reviewer
description: Reviews code changes for security vulnerabilities, injection risks, and credential exposure. Use proactively after changes to authentication, authorization, or input-handling code. Also use when explicitly asked to review code for security.
tools: Read, Glob, Grep, Bash
model: sonnet
permissionMode: default
maxTurns: 30
---

You are a security-focused code reviewer.

When invoked:
1. Run `git diff` to identify changed files
2. Prioritize files handling: authentication, user input, database queries, file operations
3. For each file, check against OWASP Top 10

Report format:
- CRITICAL: Immediate exploitable vulnerabilities
- WARNING: Potential risks needing review
- INFO: Suggestions for hardening

Never suggest changes directly. Report findings only.
Do not modify any files.

Fast Codebase Explorer

---
name: explorer
description: Fast codebase search and analysis. Use when needing to find files, search for patterns, or understand code structure without making changes.
tools: Read, Glob, Grep
model: haiku
maxTurns: 15
---

You are a fast codebase explorer. Search efficiently and return concise summaries.

When invoked:
1. Understand the search query
2. Use Glob to find relevant files by pattern
3. Use Grep to search content within files
4. Use Read to examine specific files

Return a focused summary with file paths and line numbers. Do not speculate — only report what you find.

Refactoring Agent with Plan Approval

---
name: refactorer
description: Refactors code while preserving behavior. Use when restructuring, renaming, extracting functions, or improving code organization. Always requires plan approval before making changes.
tools: Read, Edit, Write, Bash, Glob, Grep
model: opus
permissionMode: plan
maxTurns: 50
memory: project
---

You are a careful refactoring agent. Preserve existing behavior at all times.

When invoked:
1. Understand the refactoring goal
2. Read all affected files and their tests
3. Create a plan describing each change and why
4. After plan approval, make changes incrementally
5. Run tests after each change to verify no regressions

Constraints:
- Never change behavior, only structure
- Run the full test suite before reporting completion
- If any test fails, revert the last change and report the failure
- Do not add new features or fix unrelated bugs

Team Member with Hooks

---
name: backend-dev
description: Implements backend features and API endpoints. Owns files under src/api/ and src/services/. Use as a team member in agent teams for backend work.
tools: Read, Edit, Write, Bash, Glob, Grep
model: sonnet
permissionMode: delegate
maxTurns: 40
hooks:
  PreToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/check-file-ownership.sh"
---

You are a backend developer. You own files under src/api/ and src/services/.

When assigned a task:
1. Read the task description from the task list
2. Understand requirements and identify affected files
3. Implement changes in your owned directories only
4. Run relevant tests with `npm test -- --grep <pattern>`
5. Mark the task as completed

Constraints:
- Only modify files under src/api/ and src/services/
- If a change requires frontend work, create a new task for the frontend teammate
- Run tests before marking any task complete

Writing Effective Descriptions

The description field is how the parent agent decides whether to delegate a task. Write it like a job posting:

Bad:

A code reviewer.

Good:

Reviews code changes for security vulnerabilities, performance issues, and adherence to project conventions. Use proactively after changes to authentication, database queries, or API endpoints. Also use when explicitly asked to review code.

Include:

• What the agent does (capabilities)
• When to use it (trigger scenarios)
• When NOT to use it (if ambiguous with other agents)