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

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

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)

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