Agent/Subagent Authoring — Official Best Practices

File Structure

Agents are Markdown files with YAML frontmatter. The body becomes the system prompt.

.claude/agents/my-agent.md     # Project-scoped (commit to VCS)
~/.claude/agents/my-agent.md   # User-scoped (all projects)

YAML Frontmatter — All Fields

See quick-ref/frontmatter-reference.md for detailed field docs.

---
name: code-reviewer                # Required. Lowercase + hyphens
description: |                     # Required. When Claude should delegate
  Expert code review specialist. Use proactively after code changes.
tools: Read, Grep, Glob, Bash     # Allowlist (inherits all if omitted)
disallowedTools: Write, Edit       # Denylist (removed from inherited/allowed)
model: sonnet                      # sonnet | opus | haiku | inherit (default)
permissionMode: default            # default | acceptEdits | dontAsk | bypassPermissions | plan
maxTurns: 50                       # Max agentic turns before stopping
skills:                            # Skills preloaded into context at startup
  - api-conventions
  - error-handling
mcpServers:                        # MCP servers available to this agent
  - slack                          # Reference existing server by name
memory: user                       # user | project | local — persistent memory
background: false                  # true = always run as background task
isolation: worktree                # Run in temporary git worktree
hooks:                             # Lifecycle hooks (scoped to this agent)
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate.sh"
---

System Prompt (Body)

The markdown body IS the system prompt. Subagents receive ONLY this + basic env details (cwd, etc.), NOT the full Claude Code system prompt.

Effective prompt structure:

You are a [role] specializing in [domain].

When invoked:
1. [First action]
2. [Second action]
3. [Third action]

[Domain-specific checklist or criteria]

Provide feedback organized by:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider)

Include specific examples of how to fix issues.

Description — Critical for Delegation

Claude delegates based on the description. Include "Use proactively" to encourage automatic delegation.

Good: "Expert code review specialist. Use proactively after code changes." Bad: "Reviews code" — too vague, Claude won't know when to delegate.

Key Design Decisions

When to use agents vs skills vs main conversation

| Use Case | Mechanism | |----------|-----------| | Verbose output you don't need in main context | Agent | | Enforce tool restrictions | Agent | | Self-contained work returning a summary | Agent | | Reusable knowledge/instructions inline | Skill | | Frequent back-and-forth needed | Main conversation | | Quick, targeted changes | Main conversation |

Model selection

| Model | Use for | |-------|---------| | haiku | Fast exploration, simple search, low-cost | | sonnet | Balanced — code review, analysis, most tasks | | opus | Complex reasoning, architecture decisions | | inherit | Same as main conversation (default) |

Tool restrictions

Read-only agent: tools: Read, Grep, Glob, Bash
Full capabilities: omit tools (inherits all)
Block specific tools: disallowedTools: Write, Edit
Restrict spawning: tools: Agent(worker, researcher), Read

Common Patterns

See quick-ref/patterns.md for detailed examples.

Code reviewer — Read-only, focused on quality Debugger — Can edit, diagnosis-to-fix workflow Domain expert — Specialized knowledge (data science, security) Parallel research — Multiple agents exploring independently Chain — Sequential agents, each building on previous results

Memory

When memory is set, the agent gets a persistent directory across sessions.

| Scope | Location | Use when | |-------|----------|----------| | user | ~/.claude/agent-memory/<name>/ | Learnings across all projects | | project | .claude/agent-memory/<name>/ | Project-specific, shareable via VCS | | local | .claude/agent-memory-local/<name>/ | Project-specific, not committed |

The agent automatically gets Read/Write/Edit tools + instructions for managing MEMORY.md.

Tip: Include in prompt: "Update your agent memory as you discover patterns, codepaths, and architectural decisions."

Anti-Patterns

| Anti-Pattern | Fix | |--------------|-----| | Too many responsibilities | One agent, one job. Create separate agents for different tasks | | No description or vague description | Detailed description with "use proactively" | | Overly permissive tools | Grant only what's needed | | Expecting subagents to spawn subagents | Not supported. Use chains from main conversation | | Forgetting subagents lose parent context | They start fresh. Preload skills or provide full instructions |

Checklist

[ ] name and description set (both required)
[ ] Description explains WHEN to delegate, not just what
[ ] Tools restricted to minimum necessary
[ ] Model chosen based on task complexity
[ ] System prompt has clear workflow steps
[ ] Tested with real scenarios
[ ] Committed to .claude/agents/ (project) or ~/.claude/agents/ (user)