Creating Subagents (Agent Files)

Guide for creating Claude Code subagents following Anthropic's official best practices (January 2026).

File Format

Subagents are Markdown files with YAML frontmatter:

---
name: code-reviewer
description: Expert code review specialist. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer ensuring high standards.

When invoked:

1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Required Fields

Only two fields are required:

• name: Unique identifier, lowercase letters and hyphens only (kebab-case)
• description: When Claude should delegate to this subagent. Include what it does and when to use it.

Directory Locations

Priority hierarchy (higher priority wins):

1. --agents CLI flag (session only)
2. .claude/agents/ (project-level, version-controlled)
3. ~/.claude/agents/ (user-level, all projects)
4. Plugin agents/ (lowest)

Frontmatter Fields

Field	Required	Description
name	✅ Yes	Unique identifier (kebab-case)
description	✅ Yes	Delegation trigger description
tools	No	Allowlist (inherits all if omitted)
disallowedTools	No	Denylist to remove
model	No	sonnet, opus, haiku, or inherit (default)
permissionMode	No	default, acceptEdits, dontAsk, bypassPermissions, plan
skills	No	Skills to preload at startup
hooks	No	Lifecycle hooks scoped to this subagent

Creating Subagents

Three methods:

1. Interactive: /agents in Claude Code TUI
2. Manual: Create .claude/agents/my-agent.md or ~/.claude/agents/my-agent.md
3. CLI: claude --agents '{"agent-name": {...}}'

After manual creation, restart session or run /agents to load.

Writing Effective Descriptions

Critical for automatic delegation. Include:

1. What the subagent does
2. When to use it
3. Proactive triggers (recommended)

Good:

description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.

Bad:

description: Code reviewer # Too vague, missing triggers

Tool Access Control

Allowlist:

tools: Read, Grep, Glob, Bash

Denylist:

disallowedTools: Write, Edit

Default: Inherits all tools from main conversation (including MCP tools) if tools omitted.

Model Selection

model: haiku      # Fast, read-only exploration
model: sonnet     # Balanced (code review, debugging)
model: opus       # Complex reasoning
model: inherit    # Match main conversation (default)

Permission Modes

Mode	Behavior
default	Standard permission prompts
acceptEdits	Auto-accept file edits only
dontAsk	Auto-deny prompts
bypassPermissions	Skip all checks
plan	Read-only (Plan mode)

Note: Parent bypassPermissions takes precedence.

Preloading Skills

skills:
  - api-conventions
  - error-handling-patterns

Key: Full content injected at startup. Subagents don't inherit skills from parent conversation.

System Prompt Patterns

The Markdown body becomes the system prompt. Use:

• Workflow steps: "When invoked: 1. Do X 2. Do Y"
• Checklists: Structured review criteria
• Output formats: Priority-based feedback structure
• Explicit constraints: "You cannot modify data..."

Automatic Delegation

Claude delegates based on task description, description field, and context.

Encourage proactive delegation: Include "use proactively" in descriptions.

Explicit invocation:

Use the code-reviewer subagent to review my changes

When to Use Subagents

Use subagents when:

• Task produces verbose output
• Need to enforce tool restrictions
• Work is self-contained with summary return
• Want to isolate context

Use main conversation when:

• Frequent back-and-forth needed
• Multiple phases share significant context
• Quick, targeted changes
• Latency matters

Limitation: Subagents cannot spawn other subagents. Chain from main conversation or use Skills.

File Naming

• Filename: Any name ending in .md (e.g., my-agent.md)
• Name field: kebab-case (lowercase, hyphens only)
• Must be unique within scope

Loading Behavior

• Loaded at session start
• Restart session or /agents to load manually-created files
• Changes require restart

Version Control

Project subagents (.claude/agents/): ✅ Check into version control, share with team

User subagents (~/.claude/agents/): Personal preferences, keep out of version control

Reference Files

• Examples: See examples.md
• Hooks: See hooks.md for conditional tool validation
• Advanced: See advanced.md for background execution, resuming, auto-compaction

Fundamental Principle

Focused, specialized assistants with clear delegation triggers and appropriate tool restrictions. Design them to solve specific, well-defined problems that benefit from isolated context or enforced constraints.