Claude Code Subagent Generator: Build .claude/agents Files

Start from a template

Name

Saved as code-reviewer.md

Save to

Description

When should Claude delegate to it? "Use proactively…" encourages automatic use.

Tools

Model

Colour

Effort

Permission mode

Memory

Max turns

Preload skills

Comma-separated skill names to load into its context at startup.

Run in an isolated git worktreeGives the subagent its own copy of the repo

System prompt

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews code changes for bugs, security issues and readability. Use proactively after writing or changing code.
tools: Read, Grep, Glob, Bash
model: inherit
color: purple
---

You are a senior engineer reviewing a code change.

1. Run `git diff` (and `git diff --staged`) to see what changed.
2. Read the surrounding code so you understand the context.
3. Look for, in order: correctness bugs, security problems, missing error handling, missing tests, then readability.

Report findings grouped as Must fix, Should fix and Nit. For each, give the file and line, what is wrong, and a concrete fix. If the change looks good, say so briefly. Do not edit files.

Save the file, then ask Claude to "use the code-reviewer agent" or type @agent-code-reviewer. Claude Code picks up the file within seconds (restart if the agents folder is new).

Every frontmatter field

namerequiredUnique identifier of at most 256 characters, such as code-reviewer or reviewer-v2. Hooks receive this value as agent_type. The filename doesn't have to match. Names can't contain :, which is reserved for plugin-scoped identifiers such as my-plugin:reviewer

descriptionrequiredWhen Claude should delegate to this subagent

toolsTools the subagent can use, as a comma-separated string such as Read, Grep, Bash or a YAML list. Inherits every tool available to subagents if omitted. If no entry in the list resolves to a tool, the subagent usually fails to launch with an error naming the entries. To preload Skills into context, use the skills field rather than listing Skill here

disallowedToolsTools to deny, removed from inherited or specified list. Same format as tools. An entry with a specifier, such as Bash(git push *), still removes the whole tool

modelModel to use: sonnet, opus, haiku, fable, a full model ID such as claude-opus-5-5, or inherit. When you omit it, Claude Code picks the model in the subagent model order

permissionModePermission mode: default, acceptEdits, auto, dontAsk, bypassPermissions, plan, or manual as an alias for default. Ignored for plugin subagents

maxTurnsMaximum number of agentic turns before the subagent stops. When the subagent reaches the limit, Claude Code returns its output marked as partial, and Claude can resume it to continue. The partial marking requires Claude Code v2.1.246 or later

autoCompactWindowLower the auto-compact window for this subagent to a token count from 100000 to 1000000. Requires Claude Code v2.1.296 or later

skillsSkills to preload into the subagent's context at startup. The full skill content is injected, not only the description. Subagents can still invoke unlisted project, user, and plugin skills through the Skill tool

mcpServersMCP servers available to this subagent. Each entry is either a server name referencing an already-configured server (e.g., "slack") or an inline definition with the server name as key and a full MCP server config as value. Ignored for plugin subagents

hooksLifecycle hooks scoped to this subagent. Ignored for plugin subagents

memoryPersistent memory scope: user, project, or local. Enables cross-session learning

backgroundSet to true to keep this subagent in the background even when Claude asks to wait for it. By default, subagents Claude spawns from the main conversation already start in the background

omitClaudeMdSet to true to start this subagent without the user, project, and local CLAUDE.md files in its initial context; managed policy files still load, except for managed subagents. Use it for subagents that take everything they need from the delegation prompt. Ignored when the agent runs as the main session agent via --agent or the agent setting. Requires Claude Code v2.1.271 or later

effortEffort level when this subagent is active. Overrides the session effort level, but not the CLAUDE_CODE_EFFORT_LEVEL environment variable. Options: low, medium, high, xhigh, max; available levels depend on the model. See Choose an effort level

isolationSet to worktree to run the subagent in a temporary git worktree, giving it an isolated copy of the repository branched by default from your default branch rather than the parent session's HEAD. The worktree is automatically cleaned up if the subagent makes no changes

colorDisplay color for the subagent in the task list and transcript. Accepts red, blue, green, yellow, purple, orange, pink, or cyan

initialPromptAuto-submitted as the first user turn when this agent runs as the main session agent (via --agent or the agent setting). Commands and skills are processed. Prepended to any user-provided prompt. Ignored for plugin subagents

experimentalMap of experimental options. Set its cacheTtl key to 5m or 1h to choose the prompt cache lifetime for this subagent's requests, at the frontmatter's place in the cache lifetime precedence. Claude Code ignores any other value, ignores 1h while your Claude subscription is using usage credits, and reads the field only from subagent files. Requires Claude Code v2.1.248 or later

Want more ready-made agents? Browse the subagent prompt library on the homepage.

Frequently asked questions

What is a Claude Code subagent?

A subagent is a specialised assistant with its own system prompt, tools and context window. Claude delegates matching tasks to it, the subagent works separately, and only its summary comes back, which keeps the main conversation focused and its context small.

Where do subagent files go?

Project subagents go in .claude/agents/ in your repo so the team shares them. Personal ones go in ~/.claude/agents/ and work in every project. Each is a Markdown file with YAML frontmatter (name, description, tools, model) followed by the system prompt.

How do I make Claude use my subagent?

Write a description that says when to use it; "Use proactively after code changes" encourages Claude to delegate on its own. You can also ask for it by name, or type @agent-<name> to make sure it runs.

Should a subagent use a cheaper model?

Often, yes. Read-only explorers and simple runners work well on haiku or sonnet, which is faster and cheaper, while reviewers and auditors benefit from opus or inherit. Set model: inherit to use whatever the main session uses.

How do I limit what a subagent can do?

List only the tools it needs in tools, for example Read, Grep, Glob for a read-only reviewer, or remove specific ones with disallowedTools. Omitting tools gives it everything the main session has.

Sources: Subagents docs. Claude Code Agents is an independent site, not affiliated with Anthropic.

More free Claude Code tools

All tools →

CLAUDE.md generatorAnswer a few questions about your stack, commands and conventions. Get a lean, useful CLAUDE.md.SKILL.md validatorPaste a SKILL.md and check its frontmatter, name, description length and common mistakes.Plugin manifest generatorGenerate .claude-plugin/plugin.json and a marketplace.json so people can /plugin install your work.Claude models & IDsCurrent Claude model IDs, context windows, pricing and Claude Code aliases.