How to build a Claude Code subagent: the .claude/agents/ frontmatter

The 4 fields — name, description, model, tools — via a real agent file.

A subagent is one Markdown file

Defined at `.claude/agents/<name>.md`: YAML frontmatter (metadata) plus a Markdown body (the system prompt).

Key frontmatter fields

`name`, `description` (role + when to call it — be concrete), `model` (e.g. `sonnet`), and optional `tools` to restrict what it can use.

---
name: reviewer
description: Code-review specialist subagent. Use for reviewing PRs/diffs for quality, bugs, naming and security.
model: sonnet
tools: Read, Grep, Glob, Bash
---

You are a senior code reviewer.
- Review only the diff
- Give line-specific, reasoned comments
- Always flag destructive changes or security concerns

What goes in the body

Free-form Markdown describing role, behavior, output format and don'ts. Keep it to what the role actually needs — over-long prompts backfire.

How it gets invoked

The main conversation delegates when a task fits the subagent's role. It runs in an isolated context; on completion, `SubagentStop` fires.

Don't make one agent do everything

Split by role — lead/architecture, build, review, test/QA, DevOps — for better accuracy and repeatability.

You can sell what you build

A genuinely reusable subagent can be listed for free at /sell on ConfigDeck.

FAQ

Where do subagents live?

One file at `.claude/agents/<name>.md` in your project.

What frontmatter is required?

At minimum `name` and `description`. Add `model` and `tools` as needed.

How should description be written?

Concretely, in third person, covering role and when to call it.

Should one agent do everything?

No — split by role for better accuracy and repeatability.

Can I sell a subagent I built?

Yes, list it free at /sell and keep 85% of sales.

Browse ready-made subagents →Sell what you build →Learn systematically at School →