CONCEPT Specialized assistants defined as Markdown files
Subagents are specialized AI assistants that handle specific types of tasks. Each one is
a Markdown file with YAML frontmatter: the frontmatter is the configuration (name, when to
delegate, which tools, which model) and the Markdown body becomes the subagent's system prompt. When
Claude meets a task that matches a subagent's description, it delegates to that subagent, which
works independently in its own context and returns a result to the main conversation.
The core reason subagents exist is context management. Use one when a side task — running the test suite, fetching docs, sweeping log files — would flood your main conversation with output you'll never reference again. The subagent does that work in its own context window and returns only the summary, so your main thread stays clean.
CONCEPT Where they live and how you create them
Custom subagents are discovered from two main on-disk scopes:
| Location | Scope | Use for |
|---|---|---|
.claude/agents/ | Project — this codebase | Team-shared agents; check into version control |
~/.claude/agents/ | User — all your projects | Personal agents available everywhere on your machine |
Both directories are scanned recursively, so you can organise files into subfolders — but identity comes
only from the name field, not the path. To create one, the doc's recommended path is to
ask Claude to write the file for you, or write the Markdown file yourself. The
/agents command manages subagents; in current versions running it prints a reminder to ask
Claude or edit .claude/agents/ directly rather than opening a wizard.
agents directory that didn't exist when the session started.Claude Code also ships built-in subagents — Explore (fast read-only search),
Plan (research during plan mode), and general-purpose (complex multi-step work) —
that Claude uses automatically. Your custom types extend, not replace, these.
DIAGRAM A file on disk becomes a delegatable worker
YAML frontmatter + system-prompt body"] --> LOAD["Claude Code loads it
as a named subagent"] LOAD --> MATCH{"Task matches its
description?"} MATCH -->|"yes"| SPAWN["🟢 Delegate:
runs in its OWN context window"] MATCH -->|"no"| MAIN["Stays in main conversation"] SPAWN --> RET["Returns only a summary
to the main agent"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef file fill:#e7f1ff,stroke:#4a90d9,color:#1a3a5a; class SPAWN ok; class RET ok; class F file;
CODE A minimal subagent file
The frontmatter is metadata + config; everything below the closing --- is the system prompt
that guides the subagent.
# file: .claude/agents/code-reviewer.md --- name: code-reviewer description: Reviews code for quality and best practices tools: Read, Glob, Grep model: sonnet --- You are a code reviewer. When invoked, analyze the code and provide specific, actionable feedback on quality, security, and best practices.
name and description are required. Omit tools and
the subagent inherits every tool; omit model and it inherits the main conversation's model.TRADE-OFFS Delegate to a subagent vs. stay in the main thread
✅ Reach for a subagent when
- The task produces verbose output you won't reference again
- You want to enforce specific tool restrictions
- The work is self-contained and can return a summary
⚠️ Stay in the main conversation when
- The task needs frequent back-and-forth / iteration
- Multiple phases share significant context
- It's a quick, targeted change — or latency matters (a subagent starts fresh)
EXAM TRAPS
settings.json." → Custom subagents are
Markdown files with YAML frontmatter in .claude/agents/ (project) or
~/.claude/agents/ (user), not JSON settings entries./agents to build one." → You can just ask Claude to
write the file, or author the Markdown by hand. /agents is one way to manage them, not the only way.PRACTICE
Q1 · In one sentence, what is a subagent and why use one?
A subagent is a specialized AI assistant — a Markdown file with YAML frontmatter — that Claude delegates matching tasks to; it runs in its own context window and returns only a summary, keeping verbose side-work out of your main conversation.
Q2 · Where do project vs. user subagents live, and what's the difference?
Project subagents live in .claude/agents/ and apply to that codebase (check them
into version control for the team). User subagents live in ~/.claude/agents/ and are available in
all your projects on that machine.
Q3 · Which part of the file becomes the subagent's system prompt?
The Markdown body below the frontmatter. The YAML frontmatter (name,
description, tools, model) is configuration; the body is the prompt.