How to Create Claude Code Subagents: A Step-by-Step Guide

Step 1: Decide where the subagent lives

Claude Code looks for subagents in a few places. If two have the same name, the higher-priority location wins:

• Managed settings — organisation-wide agents set by an admin (highest priority)
• The --agents command-line flag — for the current session only
• .claude/agents/ — this project; commit it so your team shares the agent
• ~/.claude/agents/ — your personal agents, available in every project
• A plugin's agents/ folder — wherever that plugin is enabled (lowest priority)

Claude Code scans these folders recursively, so you can organise agents into subfolders. An agent's identity comes from its name field, not its filename.

Step 2: Write the file

Create a file such as .claude/agents/code-reviewer.md. The YAML block at the top must start on the very first line. Everything after it is the agent's system prompt.

---
name: code-reviewer
description: Reviews recently changed code for bugs, security issues and readability. Use proactively after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior code reviewer. When invoked:

1. Look at the files that changed most recently.
2. Check for bugs, security problems, missing error handling and unclear names.
3. Report findings grouped as Critical, Warnings and Suggestions.
4. For each finding, quote the line and explain the fix.

Do not edit files. Only report.

You can also simply ask Claude to write it for you: describe the agent you want and where to save it. In current versions, running /agents prints a reminder to do exactly that; older versions opened an interactive wizard.

Step 3: Choose the frontmatter fields

Only name and description are required. These optional fields are the ones you'll use most:

• tools — an allowlist, e.g. Read, Grep, Glob. Leave it out and the agent inherits the main conversation's tools
• disallowedTools — a denylist, handy when you want everything except, say, Bash
• model — sonnet, opus, haiku, fable, a full model ID, or inherit to match the main conversation
• permissionMode — for example plan for a read-only researcher, or acceptEdits for a trusted fixer
• maxTurns — stops the agent after a set number of turns
• skills — skills whose content is loaded into the agent when it starts
• isolation: worktree — runs the agent in a temporary git worktree so its edits don't touch your files
• color — red, blue, green, yellow, purple, orange, pink or cyan, to tell agents apart

Field names are case-sensitive and must match exactly. Unknown fields are ignored silently, so a typo like Tools instead of tools quietly does nothing.

Step 4: Write a description Claude will act on

Claude decides when to delegate by reading each agent's description alongside your request. Vague descriptions get ignored. Good ones say what the agent does and when to use it — and Anthropic's docs suggest phrases like "use proactively" if you want Claude to reach for it without being asked.

• Weak: "Helps with tests"
• Strong: "Writes and fixes unit tests for TypeScript code. Use proactively after adding or changing a function."

Step 5: Use your subagent

There are four ways to run a subagent:

1. Automatically — Claude delegates when your request matches the description
2. By asking — "Use the code-reviewer subagent to check the auth changes"
3. By @-mention — type @agent-code-reviewer to guarantee that agent runs
4. For a whole session — start Claude Code with claude --agent code-reviewer

New agent files are picked up within a few seconds. You only need to restart when you create the first file in a brand-new agents folder. Run /list-agents to see what's loaded.

Common mistakes

• The frontmatter doesn't start on line one — the file is skipped
• Missing description — the file is skipped with an error
• A name containing a colon or starting with a dash — the file is rejected
• Giving every agent every tool — limit tools so a reviewer can't run shell commands
• Overlapping descriptions — two agents competing for the same job confuse delegation

Next steps

Once you have one agent working, build a small team around your workflow: a reviewer, a test writer, a debugger. Our list of 25 subagent examples is a good place to borrow from — or install claudeagents to get 120+ tested agents for coding, SEO and marketing in one command.