Skip to main content

Custom Subagents

Custom subagents are specialized agents optimized for a specific role and domain. You define them as markdown files in the .claude/agents/ directory, and control tools, model, and permissions in fine-grained detail through YAML frontmatter.

File Formatโ€‹

A subagent file consists of YAML frontmatter plus a markdown body. The frontmatter holds the configuration; the body is the system prompt:

---
name: code-reviewer
description: Reviews code quality and security best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
System prompt

A subagent receives only this markdown body as its system prompt, not the full Claude Code system prompt (basic environment information such as the working directory is still included).

YAML Frontmatter Fieldsโ€‹

FieldRequiredDescription
nameOUnique identifier. Lowercase letters and hyphens only
descriptionOUsed by Claude to decide when to delegate
tools-Available tools. Inherits all tools if omitted. Use the Task(agent_type) syntax to restrict subagent creation
disallowedTools-Tools to block
model-sonnet, opus, haiku, inherit (default: inherit)
permissionMode-default, acceptEdits, dontAsk, bypassPermissions, plan
maxTurns-Maximum number of agentic turns
skills-Skills to load at startup (full content is injected)
mcpServers-Available MCP servers (referenced by name or defined inline)
hooks-Subagent lifecycle hooks
memory-Persistent memory scope: user, project, local
background-If true, always runs in the background (default: false)
isolation-If worktree, runs in an isolated git worktree

The tools field in detailโ€‹

The Agent(agent_type) syntax restricts which subagents can be created:

tools: Agent(worker, researcher), Read, Bash

This is an allowlist. If you omit Agent entirely, the subagent cannot create subagents. This restriction only applies when the agent runs as the main thread via claude --agent.

Task renamed to Agent

In version 2.1.63, the Task tool was renamed to Agent. Existing Task(...) references continue to work as aliases for compatibility.

permissionMode valuesโ€‹

ModeBehavior
defaultStandard permission checks
acceptEditsAutomatically approves file edits
dontAskAutomatically denies permission prompts (only explicitly allowed tools work)
bypassPermissionsSkips all permission checks (use with caution)
planRead-only exploration mode

Persistent Memoryโ€‹

The memory field gives a subagent a memory directory that persists across sessions:

ScopeLocationPurpose
user~/.claude/agent-memory/<name>/Shared across all projects (recommended)
project.claude/agent-memory/<name>/Per-project, shareable via git
local.claude/agent-memory-local/<name>/Per-project, not tracked by git

When memory is enabled:

  • Memory read/write instructions are included in the system prompt
  • The first 200 lines of MEMORY.md are loaded automatically
  • The Read, Write, and Edit tools are enabled automatically
---
name: code-reviewer
description: Code reviewer โ€” remembers patterns from previous reviews
tools: Read, Grep, Glob
memory: user
---

When reviewing code, first check your memory for patterns you found previously.
After finishing the review, save anything new you learned to memory.

Storage Locations and Precedenceโ€‹

LocationScopePrecedence
--agents CLI flagCurrent session1 (highest)
.claude/agents/Current project2
~/.claude/agents/All projects3
Plugin agents/When the plugin is active4 (lowest)

If subagents with the same name exist at multiple levels, the one with higher precedence wins.

Creating and Managing Subagentsโ€‹

There are two ways to create and manage subagents:

  • Ask Claude in natural language: Say something like "create a subagent for code review" and Claude will handle creating, editing, and deleting the files
  • Edit files directly: Write or modify markdown files in .claude/agents/ (project) or ~/.claude/agents/ (user)
/agents wizard removed

In version 2.1.198, the /agents interactive wizard (the view/create/edit/delete menu) was removed. Use one of the two approaches above instead โ€” ask Claude, or edit files in .claude/agents/ directly.

CLI Definitions (--agents)โ€‹

Define session-scoped subagents as JSON:

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

Supported fields: description, prompt, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, memory.

Isolated Execution (Worktree)โ€‹

Setting isolation: worktree makes the subagent run in an isolated copy inside a git worktree:

---
name: experimental-refactor
description: Performs experimental refactoring in an isolated environment
isolation: worktree
tools: Read, Write, Edit, Bash
---

Experiment with the code freely. If there are no changes, the worktree is cleaned up automatically.

Hook Integrationโ€‹

You can define hooks directly in a subagent's frontmatter. They run only while that subagent is active and are cleaned up when it finishes:

---
name: safe-executor
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
  Stop:
    - hooks:
        - type: prompt
          prompt: "Check whether all tasks are complete: $ARGUMENTS"
---

The Stop hook is automatically converted to SubagentStop at runtime.

Practical Examplesโ€‹

Database specialist agentโ€‹

---
name: db-expert
description: Database schema analysis and query optimization
tools: Read, Grep, Glob, Bash(psql *)
model: sonnet
memory: project
---

You are a database expert.
- Always verify index efficiency when analyzing schemas
- Back up query optimization suggestions with EXPLAIN output
- Include a rollback strategy when writing migrations

Security audit agentโ€‹

---
name: security-auditor
description: Security vulnerability scanning โ€” focused on the OWASP Top 10
tools: Read, Grep, Glob
model: opus
permissionMode: plan
---

You are a security auditor. Using the OWASP Top 10 as your standard:
1. Check for SQL injection possibilities
2. Identify XSS vulnerabilities
3. Verify authentication and authorization logic
4. Check for sensitive data exposure
5. Propose specific fixes

Documentation agentโ€‹

---
name: doc-writer
description: Automatically generates API documentation and READMEs
tools: Read, Glob, Grep, Write, Edit
model: sonnet
skills:
  - doc-template
---

You are a technical writer.
You analyze code and write clear, practical documentation.
Follow the format defined by the doc-template skill.
Design principles
  • Focus on a single role: Each subagent should own exactly one specialty. A focused agent is more accurate than a general-purpose one
  • Detailed descriptions: Claude looks at description to decide whether to delegate. "Reviews code quality and security best practices" produces more accurate delegation than "code review"
  • Least tool privilege: Grant only the tools you need. A read-only agent has no reason to have Write/Edit
  • Cost control: You can specify a faster, cheaper model with model: sonnet or model: haiku. Haiku suits exploration work; Sonnet suits complex analysis
  • Watch the result size: A subagent's results are returned into the main conversation. If several subagents return detailed results, they can consume the main context quickly
  • Commit to git: Store project subagents in .claude/agents/ and share them with your team
Subagent constraints

Subagents cannot create other subagents. If you need nested delegation, use Skills, or call subagents sequentially from the main conversation.

Last updated on