What is a Claude Code subagent definition file, and how do its frontmatter and its Markdown body each shape the subagent?
answer
- Markdown plus YAML frontmatter
- two required fields
- what the body becomes
- unknown fields fail silently
- /agents stopped being a wizard
basics
~20 sA subagent is a Markdown file in .claude/agents/ or ~/.claude/agents/: YAML frontmatter configures it (name and description required; tools, model, permissionMode and others optional) and the body becomes its system prompt in place of Claude Code's own.
solid answer
~40 sA subagent definition is a Markdown file with YAML frontmatter, kept in `.claude/agents/` for one project or `~/.claude/agents/` for all of yours. Only `name` and `description` are required: `name` is the identity (the filename does not matter) and `description` is what Claude reads to decide when to delegate. Optional fields narrow it: `tools` and `disallowedTools`, `model`, `permissionMode`, `skills`, `mcpServers`, `memory`, `isolation`, `hooks`, `maxTurns`. The body is the subagent's system prompt: it gets that plus environment details, not Claude Code's own system prompt, though custom subagents still load your `CLAUDE.md` files. A misspelled field is ignored without an error, and a file missing `name` or `description` is skipped silently. Since v2.1.198 `/agents` only prints where these files live; you ask Claude to write one or edit it yourself.
code
markdown · 15 lines---
name: security-reviewer
description: Reviews changed code for injection, authorization and secret-handling flaws. Use after edits to auth or input handling.
tools: Read, Grep, Glob
model: inherit
---
You are a security reviewer. You never modify files.
When invoked:
1. Read the files named in your task.
2. Look for injection, missing authorization checks and leaked secrets.
3. Report each finding as: file:line, severity, why it is exploitable, a suggested fix.
If you find nothing, say so in one line.go deeper
Recall the two directories, the two required fields, and that the body becomes the subagent's system prompt. Know Explore exists without any file.
Explain why the body must stand alone (no Claude Code system prompt behind it), which optional fields exist, and the silent-skip cases that make a file never load.
Show how you debug a subagent that never runs: debug log, validate command, restart cases, then the description. Separate what frontmatter enforces from what the prompt merely asks.
Argue where a team's constraints belong: tool limits in frontmatter that Claude Code enforces, conventions in the prompt, and shared definitions committed under .claude/agents/ with review like any code.
## What a subagent definition is A **subagent** in Claude Code is a separate assistant with its own context window, its own system prompt and its own tool access, which Claude can hand a task to. A **definition file** is how you describe one you want to reuse. It is an ordinary Markdown file with **YAML frontmatter** between two `---` lines at the very top, followed by Markdown prose. Where the file lives decides who can use it: - `.claude/agents/` inside a repository: a **project** subagent, meant to be committed so the team shares it. - `~/.claude/agents/`: a **user** subagent, available in every project on your machine. - Both directories are scanned recursively, so `agents/review/security.md` is fine; the subfolder does not change the subagent's identity. Other sources exist (an organisation's managed settings, the `--agents` launch flag, plugins), and they matter when two definitions share a name, but the file format is the same everywhere. ## The frontmatter: configuration Only two fields are **required**; everything else narrows or extends the defaults. | Field | Required | What it controls | |---|---|---| | `name` | yes | The identifier Claude and hooks see. No `:`, which is reserved for plugin-scoped names. The filename does not have to match. | | `description` | yes | When Claude should delegate. It is always in Claude's context, so keep it short and specific. | | `tools` / `disallowedTools` | no | Allowlist and denylist of tools. Omit both and the subagent inherits every tool available to subagents. | | `model` | no | An alias, a full model ID, or `inherit`. | | `permissionMode` | no | The permission mode it runs in, within limits set by the main session's mode. | | `skills`, `mcpServers`, `memory`, `hooks`, `isolation`, `maxTurns`, `effort` | no | Preloaded skills, scoped MCP servers, persistent memory, lifecycle hooks, a worktree, a turn cap, an effort level. | Multi-word fields are **camelCase** (`disallowedTools`, `permissionMode`, `maxTurns`) and must match exactly. Claude Code **ignores a field it does not recognise without reporting anything**, so `disallowed-tools:` or `tool:` silently does nothing and the subagent keeps its inherited tools. ## The body: the whole system prompt Everything after the closing `---` becomes the subagent's **system prompt**. This is the part people underestimate: the subagent receives that prompt plus basic environment details such as the working directory, **not** Claude Code's own system prompt. So the body has to say what the subagent is for, how to work, and what shape its final report should take. A custom subagent does still load your `CLAUDE.md` hierarchy and a git status snapshot as part of its starting context, unless its frontmatter sets `omitClaudeMd: true`. It does not see the main conversation's history; it starts from the task message Claude writes when delegating. ## Files Claude Code skips without telling you A definition that never gets used is usually one that never loaded. Claude Code skips a file, reporting nothing in the session, when: 1. it has no `name` (treated as documentation kept beside your agents); 2. the opening `---` is not on the first line; 3. the `name` starts with `-` or contains `:`; 4. it has a `name` but no `description`; 5. the YAML does not parse. Run with `--debug` to see the reasons in the debug log, or run `claude plugin validate .claude/agents` to find frontmatter that does not parse. Two files in one directory tree with the same `name` load only one of them, chosen by filesystem order; `/doctor` reports such duplicates. ## Creating and editing since v2.1.198 Before v2.1.198, `/agents` opened an interactive wizard for creating, editing and deleting subagents. Since v2.1.198 it only **prints a reminder** of the two directories and suggests asking Claude. The working routes now are: 1. ask Claude to write the file ("create a read-only security reviewer in .claude/agents/"), then review the frontmatter it wrote; 2. write or edit the file yourself. Claude Code **watches** both directories, so an edit is picked up within seconds and the next delegation uses it. A restart is still needed when the `agents` directory did not exist when the session started. ## What you get without writing a file Claude Code ships **built-in subagents**: **Explore**, a fast read-only agent for searching a codebase; **Plan**, a read-only research agent used during plan mode; and **general-purpose**, which has every tool available to subagents. Explore and Plan skip your `CLAUDE.md` files and the git status snapshot to stay fast. A project or user file named `Explore` overrides the built-in one, which is how you change its model. ## Why the anatomy matters The two halves do different jobs. The **frontmatter is enforced by Claude Code**: a tool missing from `tools` is not available, unless another field such as `memory` adds it. The **body is guidance to the model**: "never edit files" in the prompt shapes behaviour, but only the tool list makes it impossible. Safe delegation comes from putting each constraint in the half that can actually hold it.
- You saved a new subagent file but Claude never delegates to it. What do you check first?Whether it loaded at all: `name` and `description` both present, the opening `---` on line one, YAML that parses, and no `:` in the name; `--debug` shows skip reasons. If the `agents` directory was created after the session started, restart. If it loaded, the `description` is probably too vague to match the task.
- Does a custom subagent see the project's CLAUDE.md?Yes. A custom subagent loads every level of the `CLAUDE.md` hierarchy the main conversation loads, unless its frontmatter sets `omitClaudeMd: true`, which keeps only managed policy files. The built-in Explore and Plan agents skip `CLAUDE.md` and the git status snapshot regardless.
- The filename is the subagent's name, so renaming the file renames the agent.
- The body is appended to Claude Code's default system prompt.
- A misspelled frontmatter field makes Claude Code reject the file with an error.
- Run /agents to open the wizard and create a new subagent.
- Only name is required; description is optional and defaults to the body.
Assumes Claude Code 2.1.286; since 2.1.198 /agents only prints the definition-file locations instead of opening a wizard.