custom-agent

[IMPORTANT] Use TaskCreate to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI may ask user whether to skip.

Quick Summary

Goal: Create new custom agents, audit existing agent quality, or enhance agent definitions.

Workflow: Detect mode (Create/Audit/Enhance) from $ARGUMENTS → Execute → Validate

Key Rules:

• Agent files: .claude/agents/{name}.md with YAML frontmatter + markdown body as system prompt
• Agent does NOT inherit Claude Code system prompt — write complete instructions
• Minimize tools to only what the agent needs
• System prompt structure: ## Role → ## Workflow → ## Key Rules → ## Output

Modes

Mode 1: Create Agent

1. Clarify — AskUserQuestion: purpose, read-only vs read-write, model preference, memory needs
2. Check Existing — Glob .claude/agents/*.md for similar agents. Avoid duplication.
3. Scaffold — Create .claude/agents/{name}.md using frontmatter template below
4. Write System Prompt — Structure: ## Role → ## Workflow → ## Key Rules → ## Output
5. Validate — Run audit checklist below

Mode 2: Audit Agents

1. Discover — Glob .claude/agents/*.md
2. Parse — Read first 30 lines of each, extract frontmatter
3. Validate — Check each audit rule below
4. Report — Issues grouped by severity (Error > Warning > Info), include quality scores
5. Fix — If user confirms, fix Error-level issues automatically

Mode 3: Enhance Agent

1. Read — Load specified agent file
2. Analyze — Check against best practices and audit checklist
3. Recommend — List improvements with rationale
4. Apply — If user confirms, apply enhancements

Agent Frontmatter Schema

---
# REQUIRED
name: my-agent                    # Lowercase + hyphens only
description: >-                   # Claude uses this to decide when to delegate
  Use this agent when [specific trigger scenarios].

# OPTIONAL — Tools
tools: Read, Grep, Glob, Bash     # Allowlist (omit both → inherits all)
disallowedTools: Write, Edit      # Denylist (removes from inherited set)
# Task(agent1, agent2) restricts spawnable subagents

# OPTIONAL — Model
model: inherit                    # inherit | sonnet | opus | haiku

# OPTIONAL — Permissions
permissionMode: default           # default | acceptEdits | dontAsk | bypassPermissions | plan

# OPTIONAL — Limits
maxTurns: 30                      # Prevents runaway agents

# OPTIONAL — Skills (content injected at startup)
skills:
  - skill-name

# OPTIONAL — MCP Servers
mcpServers:
  - server-name

# OPTIONAL — Hooks (scoped to this agent)
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate.sh"

# OPTIONAL — Memory (MEMORY.md auto-injected, Read/Write/Edit auto-added)
memory: project                   # user (~/.claude/agent-memory/) | project (.claude/agent-memory/) | local (gitignored)

# OPTIONAL — Execution
background: false                 # true = always background task
isolation: worktree               # Run in temporary git worktree
---

Tool Restriction Patterns

Available tools: Read, Write, Edit, MultiEdit, Glob, Grep, Bash, WebFetch, WebSearch, Task, NotebookRead, NotebookEdit, TaskCreate, TaskUpdate, AskUserQuestion, + MCP tools.

Model Selection

Description Best Practices

# BAD — too vague, Claude won't auto-delegate
description: Reviews code

# GOOD — specific trigger conditions
description: >-
  Use this agent for comprehensive code review after implementing features,
  before merging PRs, or when assessing code quality and technical debt.

• Include "Use this agent when..." phrasing with concrete scenarios
• Add "use proactively" to encourage auto-invocation

Common Anti-Patterns

Context Passing

• Agent receives ONLY its system prompt + task prompt — NOT parent conversation
• Parent receives ONLY agent's final result — NOT intermediate tool calls
• This isolation is the primary context management benefit

Audit Checklist

Quality Score: Valid frontmatter (20) + Description >50 chars (20) + Tools restricted (15) + Role section (15) + Workflow section (10) + Model set (10) + maxTurns set (10) = 100. Rating: 80+ Excellent, 60-79 Good, 40-59 Needs Work, <40 Poor.

File Priority (highest first)

1. --agents CLI flag (session only)
2. .claude/agents/*.md (project)
3. ~/.claude/agents/*.md (user)
4. Plugin agents/ directory

Same name across levels: higher-priority wins. Use claude agents CLI to list all.

Requirements

$ARGUMENTS

IMPORTANT Task Planning Notes (MUST FOLLOW)

• Always break work into small todo tasks
• Always add a final review todo task