How to Create Custom Claude Code Subagents

Custom Claude Code subagents are Markdown files with YAML frontmatter. You put them in a project directory or in your home folder, write a clear description of when Claude should use them, and they take the side work—reviews, research, scans—into their own context window. The main conversation gets the summary, not the raw search results, logs, or file dumps.

This is a configuration walkthrough for those files. As of Claude Code v2.1.198, /agents no longer opens an interactive creation wizard. Running it prints a reminder to ask Claude or edit .claude/agents/ yourself. The file format, frontmatter fields, and the .claude/agents/ and ~/.claude/agents/ locations did not change. Only the terminal wizard is gone.

Why define a custom worker

Use a subagent when a side task would flood the main conversation with material you will not reference again. Define a custom subagent when you keep spawning the same kind of worker with the same instructions.

Each custom worker runs in its own context window with a custom system prompt, specific tool access, and independent permissions. When Claude encounters a task that matches the subagent’s description, it delegates. Write that description so the match is obvious.

Subagents help you:

Preserve context by keeping exploration and implementation out of the main conversation
Enforce constraints by limiting which tools a worker can use
Reuse configurations across projects with user-level files
Specialize behavior with focused system prompts
Control costs by routing tasks to faster, cheaper models like Haiku

They work within a single session. Parallel independent sessions, cross-session messaging, and coordinated agent teams are separate features.

Create a user-level agent

The official quickstart builds a personal code-improver available in every project on your machine. In Claude Code, describe the subagent and where to save it:

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

Claude writes a file with a name, a description, a tools list, a model, and a system prompt. Open ~/.claude/agents/code-improver.md and confirm the frontmatter matches what you asked for:

---
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.

Because the file lives in ~/.claude/agents/, it is available in every project. To scope it to one codebase, move it to that project’s .claude/agents/ directory and check it into version control so the team can share it.

Then ask Claude to delegate:

Use the code-improver agent to suggest improvements in this project

In the transcript, delegation appears as a tool call row with the subagent’s name and a short task description, such as code-improver (Suggest code improvements).

If Claude cannot find the new subagent, restart Claude Code. A running session does not detect a newly created agents directory. This happens only when ~/.claude/agents/ did not exist before the session started.

You can also write the Markdown by hand. Claude Code watches ~/.claude/agents/ and .claude/agents/. Edits in a directory that already existed when the session started are picked up within a few seconds, with no restart. Three cases still need a restart: creating a scope’s first agent file in a brand-new agents directory; adding or editing agents under a directory added with --add-dir or /add-dir (those folders are not watched); and sessions started with --disable-slash-commands, which do not watch these directories at all.

Frontmatter that actually matters

Only name and description are required.

name is a unique identifier using lowercase letters and hyphens. The filename does not have to match. Names cannot contain :, which is reserved for plugin-scoped identifiers. Claude Code skips a file whose name contains a colon and logs an error to the debug log.

description is how Claude decides when to delegate. Write it so the handoff is obvious.

Optional fields from the official table include:

tools — tools the subagent can use. If omitted, it inherits every tool available to subagents. If no entry in the list resolves to a tool, the subagent usually fails to launch.
disallowedTools — tools to deny, removed from the inherited or specified list
model — sonnet, opus, haiku, fable, a full model ID, or inherit. Omitted defaults to inherit
permissionMode — default, acceptEdits, auto, dontAsk, bypassPermissions, plan, or manual as an alias for default (manual needs v2.1.200 or later). Ignored for plugin subagents
maxTurns, skills, mcpServers, hooks, memory, background, effort, isolation, color, and initialPrompt

The Markdown body becomes the system prompt. Subagents receive only that prompt plus basic environment details like the working directory, not the full Claude Code system prompt.

Claude Code skips a project, user, or managed agent file—without reporting it in the session—when there is no name, a name that starts with - or contains :, a name but no description, or YAML that does not parse. Run Claude Code with --debug to see the debug log.

Where the file lives, and who wins

When multiple subagents share the same name, Claude Code uses the one from the higher-priority location:

Managed settings (organization-wide, highest)
The --agents CLI flag (current session only)
Project .claude/agents/
User ~/.claude/agents/
A plugin’s agents/ directory (lowest)

Project subagents are discovered by walking up from the current working directory. As of v2.1.178, when nested .claude/agents/ directories define the same name, the definition closest to the working directory wins. Both project and user directories are scanned recursively; you can organize files into subfolders such as agents/review/. Identity comes only from the name field, not the path. Keep names unique across the whole tree: two files under the same .claude/agents/ directory that share a name load only one of them, chosen by filesystem read order. /doctor reports those duplicates.

For a one-off session, pass JSON with --agents instead of writing a file. Use prompt for the system prompt—the equivalent of the Markdown body. The flag also accepts frontmatter fields including description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, initialPrompt, memory, effort, background, and isolation. Those definitions exist only for that session:

claude --agents '{
 "code-reviewer": {
 "description": "Expert code reviewer. Use proactively after code changes.",
 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
 "tools": ["Read", "Grep", "Glob", "Bash"],
 "model": "sonnet"
 }
}'

Plugin agents load automatically but ignore hooks, mcpServers, and permissionMode. If you need those fields, copy the file into .claude/agents/ or ~/.claude/agents/.

A user or project subagent named Explore overrides the built-in Explore agent and keeps its own model field. Define one with model: haiku if you want exploration on a lower-cost model.

Built-ins you may want to deny

Claude Code still registers built-in subagents in interactive sessions: Explore, Plan, general-purpose, plus helpers such as claude, statusline-setup, and claude-code-guide. Custom files sit on top of that set.

To restrict built-ins:

Block a specific built-in type by adding it to permissions.deny
Prevent any delegation by denying the Agent tool itself
Remove only Explore and Plan with CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 (v2.1.198 or later)
In non-interactive mode and the Agent SDK, set CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 to remove all built-in types and supply only your own

If an Agent tool call omits subagent_type and the session has no general-purpose subagent to fall back on, it fails with subagent_type is required.

On Claude Code v2.1.197 and earlier, /agents still opened a wizard with Running and Library tabs. Treat that as historical. New work is files on disk.

Ask Claude to write a user-level agent under ~/.claude/agents/ for a task you already repeat—code review, research, or a read-only scan—then restart if that directory is new to the session. After it delegates once, open the official sub-agents documentation and tighten the description, tools, and model fields so the next handoff is automatic.

Sources

Subagents