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