What Is a Claude Code Sub-Agent?

The one-paragraph version

A Claude Code sub-agent is a small markdown file with a block of YAML frontmatter on top. The frontmatter declares the agent's name, a description of when it should be used, an optional list of tools it's allowed to call, an optional model, and an optional colour. Everything below the frontmatter is the agent's system prompt. The file lives at agents/<name>.md inside a project (or inside a plugin). When Claude Code reads it, it gets a focused assistant it can hand specific work to. The canonical reference is the Claude Code subagents documentation — this page is a working companion to it.

Anatomy of the file

Here is a complete, minimal example:

---
name: code-reviewer
description: Use this agent when you have just written or modified code and want a review pass before committing. For example, after implementing a feature or when the user asks for a code review.
tools: Read, Grep, Glob, Bash
model: sonnet
color: green
---

You are a senior code reviewer. When invoked:

1. Run `git diff` to see what changed.
2. Focus on correctness, security, readability, and test coverage.
3. Report findings grouped by severity (blocking / should-fix / nitpick).
4. For each finding, point at the exact file and line and suggest a concrete fix.

Be direct. Praise sparingly. Never approve code you have not actually read.

The frontmatter keys

• name — a kebab-case slug. It is also the filename (agents/code-reviewer.md) and how the agent is referred to. Use lowercase letters, numbers and single hyphens; no spaces.
• description — a natural-language description of when the agent should be used. This is the single most important field, because Claude Code uses it to decide whether to delegate a task to this agent automatically. Vague descriptions (“helps with code”) rarely get invoked; descriptions with concrete triggers (“Use this agent when…”, “for example, after a refactor…”) do.
• tools — optional, a comma-separated list of tool names the agent may use, e.g. Read, Grep, Bash. If you omit the key entirely, the agent inherits every tool available to the parent conversation. Narrowing the toolset is a good way to keep an agent focused (and to keep a read-only agent read-only).
• model — optional, one of sonnet, opus, haiku, or inherit. Omitting it (or setting inherit) means the agent runs on whatever model the parent conversation is using.
• color — optional, a colour from the documented enum (red, orange, yellow, green, cyan, blue, purple, pink). Purely cosmetic — it tints the agent in the UI.

The body

Everything after the closing --- is the agent's system prompt. Treat it like you would any system prompt: state the role, give a procedure, set expectations about output format, and call out anything the agent must not do. The body is plain markdown, so headings, lists and fenced code blocks are all fine.

Where the file lives

Project-scoped agents go in .claude/agents/ at the repo root. User-scoped agents (available everywhere) go in ~/.claude/agents/. Plugins ship agents in an agents/ directory inside the plugin. In all cases the rule is the same: one markdown file per agent, named after the name key.

How auto-invocation works (and how to make it reliable)

When you give Claude Code a task, it considers the available agents and reads their description fields to decide whether one of them is a better fit than handling the work itself. You can also invoke an agent explicitly by name. To make automatic invocation reliable:

• Lead with “Use this agent when…” so the description reads as a trigger condition, not a feature list.
• Include one or two concrete examples of situations that should trigger it.
• Be specific about scope — an agent described as doing “everything” competes with the main assistant for every task and usually loses.
• If two agents have overlapping descriptions, tighten both until they don't.

Common mistakes

• Spaces or capitals in name. It must be kebab-case; otherwise the file won't load cleanly.
• Treating tools as a YAML list. In sub-agent frontmatter it is a comma-separated string, e.g. tools: Read, Bash — not a - list.
• A description with no triggers. If it never says when to use the agent, it will rarely be used.
• An empty body. Frontmatter without a system prompt gives the agent nothing to work from.

Build one without hand-editing YAML

Getting the frontmatter shape exactly right by hand is fiddly — that's why this tool exists. The Claude Code Agent & Slash-Command Builder gives you a form for each field, validates the slug, model and tool names as you type, warns when a description has no trigger examples, and shows a live preview of the assembled agents/<name>.md file to copy or download. When you need the prompt-template format instead, read the companion slash-command frontmatter reference, or — if you're deciding which to write — see sub-agent vs. slash command.