Custom Agents

You write a prompt so specific it only applies to one workflow — security review of Dockerfiles. Pasting it into every claude -p call is tedious and error-prone. You need a reusable agent you can invoke by name, with its own tool restrictions and permissions baked in.

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.

The --brief Flag

The --brief flag modifies Claude’s system prompt to produce more concise responses. Despite documentation suggesting it enables the SendUserMessage tool, testing confirms it does not add any new tools to the session.

What --brief actually does:

• Modifies the system prompt — confirmed by different cache creation tokens (9,245 new tokens vs 0 for the standard prompt)
• Does NOT enable SendUserMessage — the stream-json init event shows the same tool list with or without --brief
• Does NOT change output format — JSON and stream-json output structure is identical
• Compatible with agents — works alongside --agent and --agents without conflict

# With --brief (different system prompt cached)
claude -p "Summarize this file" --brief --output-format json
# Output: same structure, same fields, potentially shorter result text

# Without --brief (standard system prompt)
claude -p "Summarize this file" --output-format json
# Output: same structure, result may be more verbose

Agent Selection with --agent

The --agent flag (singular) selects a named agent for the entire session. It discovers agents from three sources in priority order:

1. CLI inline — --agents '{"name": {...}}' (highest priority)
2. Project agents — .claude/agents/name.md
3. User agents — ~/.claude/agents/name.md

# Select a file-based agent
claude -p "Review this code" --agent code-reviewer --output-format json

# Select an inline agent
claude -p "Review this code" \
  --agents '{"reviewer": {"description": "...", "prompt": "..."}}' \
  --agent reviewer --output-format json

# List all discoverable agents
claude agents

The claude agents command shows all available agents grouped by source:

6 active agents

Project agents:
  code-reviewer · sonnet

Built-in agents:
  claude-code-guide · haiku
  Explore · haiku
  general-purpose · inherit
  Plan · inherit
  statusline-setup · sonnet