How to create a custom Claude Code subagent

Subagents are specialized assistants for a specific kind of task. Each one runs in its own context window with a custom system prompt, specific tool access, and independent permissions, then returns a summary instead of leaving search results, logs, or file contents in the parent conversation. Define a custom one when you keep spawning the same worker with the same instructions.

Those separate requests count toward the same usage limits as the main conversation. What you keep is a cleaner parent context, a tool list you can restrict, a configuration you can reuse, and the option to route that work to a faster, cheaper model such as Haiku. Subagents work within a single session.

Write the Markdown file

The quickstart is to ask Claude to create the file, review it, then ask Claude to use it. 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 the file with a name, a description, a tools list, a model, and a system prompt. Open ~/.claude/agents/code-improver.md. The walkthrough result looks like this:

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

A file in ~/.claude/agents/ is available in every project on your machine. To scope it to one project, move it to that project's .claude/agents/ directory and check it into version control so the team can use it.

Ask Claude to delegate:

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

You can also write the file by hand. Frontmatter goes between --- markers, and the Markdown body is the system prompt. Only name and description are required. The subagent receives that prompt plus basic environment details such as the working directory, not the Claude Code system prompt. Unrecognized fields are ignored with no error. The filename does not have to match name, and a name cannot contain :.

Choose project or user scope

Location sets who can use the agent. Same-name definitions use the higher-priority location:

Managed settings, organization-wide, deployed as Markdown files in .claude/agents/ inside the managed settings directory.
--agents, for the current session only.
.claude/agents/, the current project.
~/.claude/agents/, all of your projects.
A plugin's agents/ directory, where the plugin is enabled. This is the lowest priority.

Project agents are discovered by walking up from the current working directory. If nested project directories define the same name, the definition closest to the working directory wins. A directory added with --add-dir or /add-dir also loads its .claude/agents/ folder.

Claude Code scans .claude/agents/ and ~/.claude/agents/ recursively. A subfolder does not change identity, because identity comes only from name. If two files under the same .claude/agents/ directory, including subfolders, declare the same name, only one loads, chosen by filesystem read order. /doctor reports those same-directory clashes.

A new agents directory is not detected until Claude Code restarts. The watcher covers only directories that existed when the session started. After that, an edit is picked up within a few seconds, and the next delegation uses the updated definition. Restart is also required for agents inside a directory added with --add-dir or /add-dir, and for sessions started with --disable-slash-commands, which do not watch these directories.

Running /agents prints a reminder to ask Claude or edit .claude/agents/ and ~/.claude/agents/ directly.

Pass a session-only agent with --agents

CLI agents are JSON passed to --agents. They exist only for that session and are not saved to disk. Each top-level key is the agent name. Do not start a name with -. The prompt field is the system prompt, equivalent to the Markdown body, and it may be empty. An empty prompt requires Claude Code v2.1.281 or later. On macOS, Linux, and WSL:

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"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

The docs also show a Windows PowerShell form of the same object. In non-interactive mode, --agents can point at a JSON file, as in claude -p --agents ./agents.json "Review my changes". An interactive session refuses a file path. The file form requires Claude Code v2.1.281 or later.

Besides prompt, a CLI definition takes description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, initialPrompt, memory, effort, background, omitClaudeMd, and isolation. The fields color and experimental are ignored rather than rejected.

Keep the description short

Claude uses each subagent's description to decide when to delegate, so write that field as the condition for use. If the combined descriptions of your custom subagents, except the built-in ones, exceed 15,000 tokens, Claude Code warns at startup and shows the total token count. Trim description and move detail into the system prompt, which loads only when that subagent runs.

Other supported definition fields include:

tools, as a comma-separated string such as Read, Grep, Bash or a YAML list. Omit it to inherit every tool available to subagents. If no entry resolves to a tool, the subagent usually fails to launch, and the error names the entries.
model: sonnet, opus, haiku, fable, a full model ID such as claude-opus-5-5, or inherit.
permissionMode: default, acceptEdits, auto, dontAsk, bypassPermissions, plan, or manual as an alias for default.
skills, which preload the full skill content at startup, not only the description.
maxTurns, which stops the agent after that many agentic turns and returns output marked as partial so Claude can resume it. Partial marking requires Claude Code v2.1.246 or later.
effort, the effort level while this subagent is active. It overrides the session effort level, but not the CLAUDE_CODE_EFFORT_LEVEL environment variable. Options are low, medium, high, xhigh, and max; available levels depend on the model.

Plugin agents ignore hooks, mcpServers, and permissionMode. They also ignore initialPrompt. If you need the hook, MCP, or permission-mode fields, copy the file into .claude/agents/ or ~/.claude/agents/. A subfolder inside a plugin's agents/ directory becomes part of the scoped name: agents/review/security.md in plugin my-plugin registers as my-plugin:review:security.

Watch the delegation row

In the transcript, delegation appears as a tool-call row showing the subagent's name followed by a short task description, such as code-improver(Suggest code improvements).

Built-in Explore and Plan skip your CLAUDE.md files and the git status snapshot. Every other built-in and custom subagent loads both, unless omitClaudeMd is set to skip the user, project, and local CLAUDE.md files. Managed policy files still load, except for managed subagents. The field is ignored when the agent runs as the main session agent via --agent or the agent setting, and it requires Claude Code v2.1.271 or later. A user or project subagent named Explore overrides the built-in and keeps its own model field, so define one with model: haiku to run exploration on a lower-cost model.

Next step

Ask Claude to create a personal agent in ~/.claude/agents/, open the file, and confirm name and description before you invoke it. If that directory did not exist when the session started, restart Claude Code, then look for the tool-call row. For a one-session test, pass JSON to --agents instead of saving a file. If you are on Windows PowerShell, use the PowerShell form on the subagents page rather than the macOS, Linux, and WSL command above.

Sources

Subagents