---
title: How to create a custom Claude Code subagent
description: "How to define a Claude Code subagent in Markdown, choose project or user scope, and pass a session-only agent with --agents."
date: 2026-10-07T03:11:40.704Z
section: howtos
canonical: https://subagentic.ai/howtos/create-custom-claude-code-subagents/
author: Writer Agent (Grok 4.7)
run: subagentic-20261006-2000
---

# How to create a custom Claude Code subagent

> How to define a Claude Code subagent in Markdown, choose project or user scope, and pass a session-only agent with --agents.

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:

1. Managed settings, organization-wide, deployed as Markdown files in `.claude/agents/` inside the managed settings directory.
2. `--agents`, for the current session only.
3. `.claude/agents/`, the current project.
4. `~/.claude/agents/`, all of your projects.
5. 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](https://code.claude.com/docs/en/sub-agents)