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:

markdown

---
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):

•--agents CLI flag (session only)
•.claude/agents/ (project-level, version-controlled)
•~/.claude/agents/ (user-level, all projects)
•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:

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

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

Writing Effective Descriptions

Critical for automatic delegation. Include:

•What the subagent does
•When to use it
•Proactive triggers (recommended)

Good:

yaml

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

Bad:

yaml

description: Code reviewer # Too vague, missing triggers

Tool Access Control

Allowlist:

yaml

tools: Read, Grep, Glob, Bash

Denylist:

yaml

disallowedTools: Write, Edit

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

Model Selection

yaml

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

yaml

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:

code

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.