Claude Code subagents
A Claude Code subagent is a helper that Claude hands a task to. It works in its own context window, with its own system prompt, tools and permissions, and then sends back a result. You make one by writing a Markdown file with a name and a description. Claude delegates to it when a task matches that description.
How do I create a subagent?
Save a Markdown file in ~/.claude/agents/ for all of your projects, or in .claude/agents/ for one project. The file starts with YAML frontmatter, and only the name and description fields in it are required. Everything below the frontmatter becomes the subagent's system prompt.
This example comes from the Claude Code docs:
--- name: code-improver description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code. tools: Read, Grep, Glob model: sonnet --- You are a code improvement specialist. For each issue you find, explain the problem, show the current code, and provide an improved version.
To use it, ask Claude in plain words, such as "Use the code-improver agent to suggest improvements in this project." The tools line keeps this one read-only. Put project subagents in version control so the whole team can use them.
Does Claude Code come with subagents?
It does. Explore is a built-in, read-only subagent that searches a codebase. Plan is another. Claude sends codebase research to Explore so the results stay out of your main conversation.
When should I use a subagent instead of a skill?
Pick a subagent when the work would flood your chat with output, such as a long test run. It is also the right choice when you want to limit tools or when a task can return a short summary. Pick a skill for a reusable prompt or workflow that should run in your main conversation.
| Subagent | Skill | |
|---|---|---|
| Where it runs | Its own context window | Your main conversation |
| File | One .md file in an agents folder | A folder with SKILL.md |
| Sees your chat history | No | Yes |
| Good for | Noisy or self-contained work | Repeatable steps and know-how |
Can a subagent and a skill work together?
They can, in both directions. A subagent's skills field loads full skills into its context at startup. A skill can also run inside a subagent if you set context: fork in its frontmatter, and the agent field picks which subagent type to use.
FAQ
Do subagents cost extra?
Each subagent sends its own requests. Those count toward the same usage limits as your main chat.
Why can't Claude find my new subagent?
Restart Claude Code. A running session won't see the agents folder if that folder did not exist when the session began.
Are agents and subagents the same thing?
In Claude Code, the docs call these helpers subagents. The files live in folders named agents.