Agent Authoring

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

Model selection

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.

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

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