diegosouzapw 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):
--agentsCLI 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:
/agentsin Claude Code TUI - Manual: Create
.claude/agents/my-agent.mdor~/.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:
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
/agentsto 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.