Creating Your First Custom Subagent

The Agent File Format

Custom subagents live in .md files with YAML frontmatter. The filename becomes the agent type name. The frontmatter controls behavior. The body is the system prompt the agent receives at startup.

Here is the minimal valid format:

---
name: code-reviewer
description: Reviews code for quality, clarity, and potential bugs. Use this agent proactively when the user asks for a code review or when code quality is in question.
tools: Read, Glob, Grep
---

You are a careful code reviewer. Read the files specified in your task and report:
1. Any bugs or logic errors
2. Clarity and naming issues
3. Missing edge case handling

Return a structured report with severity ratings.

The name field is required. The description field is required and critically important — Claude reads it to decide when to invoke the agent automatically. The body (system prompt) tells the agent what to do and how to format its output.

Where to Put the File

Agent files can live in two places, each with different scope:

• Project scope: .claude/agents/code-reviewer.md — available only in this project, committable to version control so your team shares it
• Personal scope: ~/.claude/agents/code-reviewer.md — available in every project on your machine

When both exist with the same name, the priority order from highest to lowest is: managed policy (org-wide) → CLI --agents flag (session-only) → project scope → personal scope → plugin scope. Project-level definitions override personal ones.

Start with project scope for agents that are specific to a codebase. Use personal scope for agents you want everywhere — a general-purpose test runner, a documentation writer, a security auditor.

All the Frontmatter Fields

Beyond name and description, a subagent definition supports these optional fields:

• tools: allowlist of tools the agent can use. If omitted, the agent inherits all available tools.
• disallowedTools: denylist, applied before tools. Use to block specific tools even if the agent inherits all others.
• model: model override. Accepts sonnet, opus, haiku, fable, a full model ID like claude-opus-4-8, or inherit (default — uses whatever the parent session is using).
• permissionMode: controls how the agent handles permission prompts. Options: default, acceptEdits, auto, dontAsk, bypassPermissions, plan.
• maxTurns: maximum number of agentic turns before the subagent stops automatically.
• effort: low, medium, high, xhigh, or max.
• color: visual label in the UI — red, blue, green, yellow, purple, orange, pink, or cyan.
• background: true to always run this agent as a background task.
• isolation: worktree to run the agent in a temporary git worktree.
• initialPrompt: auto-submitted as the first user turn when this agent runs as the main session via claude --agent code-reviewer.

You do not need all of these in your first agent. Start with name, description, and tools.

Writing Descriptions That Work

The description field is how Claude knows when to invoke your agent without you explicitly asking. It reads every agent's description when deciding whether to delegate.

A good description does three things:

• States what the agent does in one sentence
• Names the specific triggers that should cause invocation
• Optionally includes the phrase "use proactively" to encourage automatic delegation

Compare these two descriptions for the same agent:

Weak: "Helps with code." — Too vague. Claude will not know when to invoke it.

Strong: "Reviews code for quality, clarity, and potential bugs. Use proactively when the user requests a code review, when a PR is mentioned, or when Claude has just written more than 50 lines of new code." — Claude knows exactly when this agent applies.

Invoking an Agent Explicitly

When you want guaranteed invocation without relying on Claude's judgment, three options are available:

• Natural language: "Use the code-reviewer agent to check src/auth.py."
• @-mention: Type @ in the Claude Code interface and pick the agent from the typeahead. This guarantees invocation.
• Whole-session mode: claude --agent code-reviewer — the entire session runs with that agent's system prompt, tools, and model. Useful when you want every interaction in a session to go through a specific agent's lens.

You can also set a default agent for a project in .claude/settings.json:

{
  "agent": "code-reviewer"
}