Custom Agents

Custom agents are specialized AI assistants defined as Markdown files with YAML frontmatter. Each agent runs in its own context window with a custom system prompt, tool restrictions, and independent permissions. You can scope them to a project, share them across all your work, or define them inline for one-off use.

Agent File Format

An agent file is a Markdown document where the YAML frontmatter defines the agent’s identity and capabilities, and the Markdown body becomes the agent’s system prompt. Save it to .claude/agents/ for project-level access or ~/.claude/agents/ for user-level access.

---
name: code-reviewer
description: Expert code review specialist. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer ensuring high standards of code quality.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- No duplicated code
- Proper error handling
- No exposed secrets
- Input validation implemented

Built-in Agents

Claude Code ships with five built-in agents. You cannot edit these, but you can override them by creating an agent file with the same name.

Custom Agent Creation

Create a Markdown file in one of two directories depending on the scope you need:

• Project-level: .claude/agents/code-reviewer.md — commit to git so your team shares the agent
• User-level: ~/.claude/agents/code-reviewer.md — available in every project on your machine

The filename (minus the .md extension) becomes the agent name, so code-reviewer.md creates an agent named code-reviewer. The name field in frontmatter must match.

When names conflict, the resolution order is:

Inline Agents

For quick testing or CI/CD pipelines, define agents inline with the --agents flag instead of creating files. The flag accepts a JSON object where each key is an agent name and each value defines the agent’s configuration:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

The JSON fields mirror the YAML frontmatter fields, with one difference: use prompt instead of the Markdown body for the system prompt. Inline agents are session-scoped and are not saved to disk.

To run an entire session as a specific agent, use --agent (singular):

claude -p "Review this code" \
  --agents '{"reviewer": {"description": "Code reviewer", "prompt": "You are a strict code reviewer. Always start with REVIEWER:"}}' \
  --agent reviewer \
  --output-format json

The agent’s system prompt replaces the default Claude Code system prompt entirely. CLAUDE.md files still load normally.

Agent(type) Tool

Within a running session, Claude can spawn subagents using the Agent tool. You do not call this tool directly — you ask Claude to delegate work to an agent by name:

Use the code-reviewer subagent to review the auth module

Or with an @-mention:

@"code-reviewer (agent)" look at the auth changes

You can restrict which agents a coordinator can spawn using the Agent(type) syntax in the tools frontmatter field:

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

Only the worker and researcher agents can be spawned from this coordinator. Using Agent without parentheses allows spawning any available agent.

Key constraints for subagents:

• Subagents cannot spawn other subagents — no nesting is allowed
• Subagents get their own system prompt, not the full Claude Code prompt
• Foreground subagents block the main conversation until complete; permission prompts pass through
• Background subagents run concurrently with permissions pre-approved upfront; press Ctrl+B to background a running task

claude agents Command

Run claude agents to see all configured agents, both built-in and custom:

In interactive mode, use the /agents slash command to create, edit, and delete agents without leaving your session. New agents created this way are available immediately without restarting.