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)

Reference

• All frontmatter fields
• Common agent patterns