How to Create a Claude Code Subagent

Every Claude Code session has one context window, and side tasks fill it up fast. Searching files, reading logs, and checking test output all leave text behind that Claude needed only once. A subagent takes those tasks off the main conversation: it does the work in its own context and hands back a short summary. Here is how to create a Claude Code subagent of your own, where to save it, and how to put it to work.

What a subagent is

A subagent is a helper that your main session hands a task to. It works in its own context window, with its own instructions, tools, and permissions, and it reports back only to the session that started it. All the searching and reading stays in the subagent's context, so the main conversation gets the answer without the clutter. Its work counts toward the same usage limits as the rest of the session.

You have probably used subagents already. Claude Code comes with a few built in, and Claude uses them on its own when a task fits: Explore searches a codebase without changing anything, Plan does research when you work in plan mode, and general-purpose handles side tasks that need several steps, including changes. Your own subagents are for the side tasks you hand off again and again, like reviewing code or running tests.

What goes into a subagent file

A subagent is a Markdown file with two parts. At the top is a short header in YAML, a simple format of names and values, between two lines of three dashes. Below it come the instructions, written in plain language, which become the subagent's own instructions. Here is a read-only code reviewer:

---
name: code-reviewer
description: Reviews Python code for bugs and readability. Use after code changes or when asked for a review.
tools: Read, Grep, Glob
model: sonnet
---

You review Python code for bugs and readability. Read the files you are asked about and report each issue with the file name, the line number, and a suggested fix. Do not change any files.

Only two settings are required. name identifies the subagent, and description tells Claude what it does and when to use it. The description matters most, because it is how Claude decides when to hand a task over, so make it clear and specific.

The other settings are optional. tools limits what the subagent can do; this reviewer can read and search files but cannot edit them. Leave tools out, and the subagent gets every tool that subagents are allowed to use. model picks the Claude model it runs on: sonnet, opus, haiku, a full model name, or inherit to use the same model as the main conversation. There are more, such as a permission mode, a limit on the number of turns, or hooks that apply only to this subagent.

One thing to watch: setting names are case-sensitive, and Claude Code silently ignores a name it does not recognize. A typo such as Tools instead of tools produces no error; the setting simply does not apply.

Where to save it

Where you save the file decides who can use it.

• Project subagents go in the .claude/agents folder inside your project. Commit that folder, and everyone working on the project gets the same subagents.
• Personal subagents go in ~/.claude/agents, the agents folder inside the .claude folder of your home directory. They work in all your projects.

If a project subagent and a personal one have the same name, the project one wins in that project. Subagents deployed by your organization and subagents passed with the --agents flag when you start Claude Code rank higher still.

Claude Code notices new and changed subagent files within a few seconds, with no restart. The exception is the first file in an agents folder that did not exist when the session started: that one loads the next time you start Claude Code.

Creating one with Claude

You do not have to write the file by hand. Describe the subagent you want, and Claude creates the file for you:

Create a project subagent named code-reviewer in .claude/agents. It reviews Python code for bugs and readability and reports each issue with the file and line. Give it only the Read, Grep, and Glob tools, and use Sonnet.

Approve the new file, then open it and check the header and the instructions before you rely on it.

If you follow an older guide, you may see the /agents command open a screen for building subagents. Current versions of Claude Code no longer have that screen: /agents only reminds you to ask Claude or to edit the agents folders directly.

Using your subagent

There are two ways to put a subagent to work. Claude delegates on its own when a task matches a subagent's description. Or you ask for it directly: name it in your request, such as "use the code-reviewer subagent to check order.py", or type @ and pick it from the list, the same way you mention a file.

In an interactive session, subagents run in the background by default. You keep working in the main conversation, and the summary arrives when the subagent finishes. To see what is running, type /tasks. It lists the work going on in the background of the session and lets you check on a task or stop it.

Conclusion

A Claude Code subagent is one Markdown file: a short header with a name, a description, and optionally its tools and model, followed by plain-language instructions. Save it in .claude/agents for a project or in ~/.claude/agents for all of them, let Claude write it for you if you like, and keep the description specific so Claude knows when to use it. Your main conversation stays focused on the work that matters, and the side tasks come back as short summaries.

Relevant Training

Subagents are covered in Claude Code Agents and Automation, part of Cybrec's Claude AI training program, together with running agents in parallel, hooks, and automation.