AI Weekly
Guides ·
How to create Claude Code subagents — one file in .claude/agents per specialist
A Claude Code subagent is one Markdown file. Where to put it, what name, description, tools and model control, when Claude delegates on its own, and a real example from the 14 subagents hiio runs.
A Claude Code subagent is a Markdown file with YAML frontmatter, and the body becomes that agent's system prompt. Put project subagents in .claude/agents/ and personal ones in ~/.claude/agents/. Only name and description are required, and leaving out tools gives the subagent every available tool. Claude decides when to delegate by reading the description, so phrases like "use proactively" make it delegate more often.
Claude Code: A Hands-On Guide · Part 4 of 10
A subagent is "this kind of work goes to this person," written down in one file. Put a name, when to delegate, and which tools it can use in a Markdown file, and Claude Code hands that work off on its own when it comes up. This guide covers where the file goes, which frontmatter fields matter, how Claude decides to delegate, and a real file from our team. It was written by AI (Claude) and checked against the official Subagents docs. hiio runs its one-person app studio with 14 subagents for design, copywriting, social posting and more.
Why use subagents
Per the official docs, a subagent works in its own context window, with its own system prompt, tools and permissions. It does not see the main conversation. It only gets the task prompt Claude writes for it, and when it finishes, it returns just a summary.
That makes subagents a good fit for:
- Searches that dig through dozens of files, so long results do not pile up in the main conversation
- Work that always follows the same rules, so you do not have to repeat them
- Work that needs a narrow set of tools, such as a read-only reviewer
Where subagent files go
| Location | Scope | Priority |
|---|---|---|
| Managed settings | Whole organization | 1 (highest) |
--agents CLI flag |
Current session | 2 |
.claude/agents/ |
This project | 3 |
~/.claude/agents/ |
All your projects | 4 |
A plugin's agents/ folder |
Where the plugin is enabled | 5 |
If the same name exists in several places, the higher-priority one wins. Subfolders are scanned too. A subagent is identified by its name value, not its file path.
What the file looks like
---
name: code-reviewer
description: Reviews code quality. Use proactively after code changes.
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. Read the changed code and list specific fixes.
The part between the --- lines is the frontmatter. The body below it becomes the agent's system prompt.
Fields you need to know
| Field | What it controls | If omitted |
|---|---|---|
name |
The name (required). Cannot contain : |
— |
description |
When to delegate (required) | — |
tools |
Which tools it can use | Inherits every available tool |
disallowedTools |
Tools to remove | — |
model |
sonnet, opus, haiku, fable, a model ID, or inherit |
Picked in a set order (below) |
permissionMode |
Permission mode | — |
memory |
Where its memory lives (user, project, local) |
— |
There are more, including maxTurns, skills, mcpServers, hooks, effort, isolation (worktree), background and color. One trap the official docs warn about: a misspelled field name is ignored without any error. Multi-word names use camelCase, like disallowedTools.
The model is chosen in this order:
- A model Claude sets for that specific delegation
- The
modelfield in the frontmatter (inheritmeans the main conversation's model) - The
CLAUDE_CODE_SUBAGENT_MODELenvironment variable - The main conversation's model
When Claude delegates
From the official docs: Claude decides when to delegate by reading each subagent's description. To make it delegate more often on its own, the docs suggest phrases like "use proactively" in the description. But keep descriptions short. If all your subagents' descriptions add up to more than 15,000 tokens, you get a warning at startup.
You can also call one directly:
- In plain words: "Use the test-runner subagent to fix the failing tests"
- With an @-mention:
@"code-reviewer (agent)" look at the auth changes - For a whole session:
claude --agent code-reviewer
Our file: the "messenger"
This is the frontmatter of jeollyeong ("messenger"), hiio's social posting agent. The tool list is shortened, and the description is translated from Korean.
---
name: jeollyeong
description: Messenger (social posting). Use proactively when publishing finished drafts to Threads, X, Instagram, LinkedIn, TikTok or GeekNews, processing the queue, or recording post links. Drafting and scheduling belong to sns-manager, headlines to copywriter. The messenger never edits text and copies it exactly.
tools: Read, Grep, Glob, Bash, Edit, mcp__claude-in-chrome__navigate, ...
model: inherit
memory: project
---
Three things we settled on after using it:
- Write what the agent does not do, and whose job that is, in the description. Lines like "drafting belongs to sns-manager" kept similar agents from overlapping.
- Give only the tools it needs. The messenger only posts, so we removed
Write. With no way to rewrite a draft, "post exactly what you got" holds. - Move shared rules into one file and have the body read it first. If 14 files each carry the company rules, one change means 14 edits. We keep
.claude/agent-shared/COMMON.md, and each body starts with "Read COMMON.md first and follow it."
What to watch out for
- Subagents can spawn their own subagents. By default, up to 3 layers below the main conversation. To stop one, leave
Agentout oftoolsor add it todisallowedTools. Setting the environment variableCLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1turns nesting off entirely. - It does not know the main conversation. The task prompt Claude writes is all it gets. That is why a line in the body saying "read this first" makes a big difference.
- Subagents shipped in a plugin ignore
permissionMode. If you are distributing one, do not rely on permissions. Narrow it with tools.
FAQ
Do I have to use the /agents command to create a subagent?
No. Create a Markdown file directly in .claude/agents/ or ~/.claude/agents/. According to the official docs, /agents in recent versions shows a reminder to ask Claude or edit those folders directly, while older versions opened a create-and-edit screen.
Does Claude Code come with built-in subagents?
Yes. They include Explore, which searches code quickly in read-only mode, Plan, which does research in plan mode, and general-purpose, for multi-step work. Explore cannot use Write or Edit.
What happens if I leave out the tools field?
The subagent inherits every tool available to it. That is convenient, but for narrow roles like reviewing or posting, listing tools explicitly leads to fewer accidents.
Which subagent wins if the same name is in my project and my home folder?
The higher-priority one: the project's .claude/agents/ (row 3 in the table above beats row 4).
Sources
- Claude Code docs — Subagents
- Claude Code permission modes: all 6 explained
- 4 Claude Code hooks examples
- eojeon on GitHub
Written with AI (Claude) and checked against the linked sources.