Claude Code ships with subagents you never wrote: Explore, Plan, and general-purpose. They cover a lot of ground. But the third time in a week you type the same fifteen-line "act as a careful reviewer, only read, never touch the database" instructions, you start wanting a real definition saved on disk instead. That is the whole point of Claude Code custom subagents. You write the job once and give it a name, you hand it a model and a tool list, and after that Claude can delegate to it by description or you can summon it by hand.
This guide assumes you already know what a subagent is and how delegation works. If you don't, start with how to use subagents in Claude Code. Here we go straight to defining your own.
Where Claude Code custom subagents live
A custom subagent is a single Markdown file with YAML frontmatter at the top and a system prompt in the body. Two locations matter for most people:
.claude/agents/in your repo, for subagents tied to one project. Check these into git so your team gets them.~/.claude/agents/in your home directory, for personal subagents that follow you into every project.
When two subagents share a name the higher-priority location wins, and project beats user. Claude Code scans both directories recursively, so agents/review/security.md works fine. The folder name itself does nothing. Identity comes only from the name field, which means you should keep names unique across the tree or one file gets silently dropped.
There is one gotcha that bites everyone exactly once. Files you add or edit on disk load at session start, so a mid-session edit changes nothing until you restart. The exception is creating it through the /agents command, which takes effect immediately. That interface is also the easiest way to generate a first draft, pick tools from a real list (including MCP tools), and choose a model without having to memorize field names.
The Claude Code subagent config fields
Here is a complete, real definition. Only name and description are required. Everything else is optional and falls back to a sensible default.
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer ensuring high standards of code quality and security.
When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately
Review checklist:
- Code is clear and readable
- No exposed secrets or API keys
- Input validation implemented
- Proper error handling
Provide feedback by priority: critical issues, warnings, suggestions.
Include specific examples of how to fix each one.
The body is the whole Claude Code subagent prompt. A subagent does not inherit the full Claude Code system prompt; it gets only what you write here, plus a few environment details like the working directory. This block is the entire personality and the entire instruction set, so write it like you mean it.
The frontmatter fields you will actually reach for:
nameis a lowercase, hyphenated identifier. Hooks see it asagent_type. The filename does not have to match.descriptionis how Claude decides when to delegate automatically. Vague descriptions get ignored. Put the trigger conditions in plain words, and "use proactively" if you want eager delegation.toolsis an allowlist. Omit it and the subagent inherits every tool the main conversation has.disallowedToolsis a denylist applied against the inherited set. Set both and the denylist runs first.modelpicks the model. More on that below.permissionMode,skills,mcpServers,hooks, andmemoryexist for finer control. The full frontmatter reference lists all of them.
Scoping the Claude Code subagent tools
Tool scope is the single most useful thing a custom subagent gives you, and most people underuse it badly. Two patterns cover almost everything.
Use an allowlist when you want a tight, predictable worker, like a reviewer that can read and search but never edit:
---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---
Use a denylist when you want everything except a couple of dangerous tools. This one keeps Bash and any MCP tools but strips file mutation:
---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---
A few tools are never available to subagents no matter what you list, because they depend on the interactive UI. AskUserQuestion, EnterPlanMode, and the Agent tool are among them. Subagents also cannot spawn other subagents, full stop, so if you need nested delegation you chain it from the main conversation instead. For running several independent workers at once, see Claude agent teams.
Choosing the Claude Code subagent model
The model field takes an alias (sonnet, opus, haiku), a full model ID like claude-opus-4-8, or the keyword inherit. Leave it out and it defaults to inherit, meaning the subagent runs on whatever the main conversation is using.
My rule of thumb is to match the model to the work rather than to the parent. A read-only explorer that greps a codebase and returns file paths does not need Opus. Put it on Haiku and it returns faster and costs less, which matters a lot when Claude fans out five of them at once. The built-in Explore agent runs on Haiku for exactly this reason. Save the expensive model for the subagents that actually reason hard about what they read, like a security reviewer, or a debugger forming hypotheses about a crash.
To override the model for one run, Claude can pass a per-invocation model, and a CLAUDE_CODE_SUBAGENT_MODEL environment variable beats both that and the frontmatter. The frontmatter is the floor.
Invoking a custom subagent
Once the file is in place, there are three ways to run it, escalating from soft to hard.
The softest is to name it in plain language and let Claude choose: "Use the code-reviewer subagent to look at my recent changes." Claude reads the description fields and decides. To force a specific one for a single task, @-mention it. You type @ and pick from the typeahead, or write @agent-code-reviewer directly. The @-mention guarantees which subagent runs, although Claude still writes the actual task prompt from your message.
The third way is the heavy one. Run an entire session as the subagent:
claude --agent code-reviewer
That replaces the default Claude Code system prompt with the subagent's body for the whole session, the way --system-prompt would. Your CLAUDE.md and project memory still load normally. Set it permanently for a project by putting "agent": "code-reviewer" in .claude/settings.json.
Two patterns worth stealing
A focused reviewer is the canonical example, and the whole reason it works is the tool list. Deny Write and Edit, and the subagent physically cannot "helpfully" rewrite your file when it was only supposed to be critiquing it. The constraint is doing the real work here. Pair that with a description that says "use immediately after writing code" and Claude starts reaching for it on its own, without you having to ask.
The other pattern is an explorer: read-only tools, Haiku, and a prompt that says "find the relevant files and report paths and line ranges, do not summarize the code." Spawn three of them at once across different modules and you get parallel research that never floods your main context with raw file dumps. For wiring several of these into a real pipeline, Claude Code multi-agent workflows covers the composition side.
The part most people skip is the prompt itself. A custom subagent's system prompt is really a job description, and a good one reads like onboarding docs for a new hire: what to do first, what to check, how to format the output, what is off limits. That is exactly the kind of artifact worth writing once and reusing across Claude Code, Codex, Cursor, and the Claude apps. Knack turns a short interview into a portable Agent Skill in the open Anthropic format, so the job you defined for one tool can travel to the rest. Author the playbook once as a skill, then preload it into a subagent with the skills field.
Start small. Take the instructions you keep retyping, drop them into .claude/agents/, scope the tools as tight as you can stand, and pick the cheapest model that still does the job well. You will know within a day or two whether the thing earned its place on disk.