[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 MUST 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

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

Modes

Mode Trigger Action

Create $ARGUMENTS describes a new agent Create agent file

Audit mentions verify, audit, review, check, quality Audit existing agents

Enhance mentions refactor, enhance, improve, optimize Improve existing agent

Mode 1: Create Agent

• Clarify — AskUserQuestion : purpose, read-only vs read-write, model preference, memory needs

• Check Existing — Glob .claude/agents/*.md for similar agents. Avoid duplication.

• Scaffold — Create .claude/agents/{name}.md using frontmatter template below

• Write System Prompt — Structure: ## Role → ## Workflow → ## Key Rules → ## Output

• Validate — Run audit checklist below

Mode 2: Audit Agents

• Discover — Glob .claude/agents/*.md

• Parse — Read first 30 lines of each, extract frontmatter

• Validate — Check each audit rule below

• Report — Issues grouped by severity (Error > Warning > Info), include quality scores

• Fix — If user confirms, fix Error-level issues automatically

Mode 3: Enhance Agent

• Read — Load specified agent file

• Analyze — Check against best practices and audit checklist

• Recommend — List improvements with rationale

• 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

Agent Type Recommended tools

Explorer/Scout Read, Grep, Glob, Bash

Reviewer (read-only) Read, Grep, Glob

Writer/Implementer Read, Write, Edit, Grep, Glob, Bash

Researcher Read, Grep, Glob, WebFetch, WebSearch

Orchestrator Read, Grep, Glob, Task(sub1, sub2)

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

Model Selection

Model Best For

haiku

Fast read-only: scanning, search, file listing

sonnet

Balanced: code review, debugging, analysis

opus

High-stakes: architecture, complex implementation. Better quality for code review, debugging, analysis

inherit

Default — match parent's model

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

Anti-Pattern Fix

No tool restrictions Add tools allowlist

Vague description Write specific trigger conditions

Giant system prompt Keep concise, use skills for detail

No maxTurns

Set 20-30 to prevent runaway

Recursive subagents Restrict Task in tools

Windows long prompts (>8191 chars) Use file-based agents, not --agents CLI

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

Check Rule Severity

1 Frontmatter exists Must have --- delimiters Error

2 Name present & valid Lowercase + hyphens only Error

3 Description present Non-empty, >20 chars Error

4 No duplicate names Unique across all agent files Error

5 Description quality Specific trigger scenarios Warning

6 Tools minimal Only what agent needs Warning

7 Prompt structure Has ## Role

• Workflow

Warning

8 Model set When task differs from default Info

9 maxTurns set Recommended 20-30 Info

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)

• --agents CLI flag (session only)

• .claude/agents/*.md (project)

• ~/.claude/agents/*.md (user)

• 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