Introduction
# Agent Development for Claude Code
Build effective custom agents for Claude Code with proper delegation, tool access, and prompt design.
## Agent Description Pattern
The description field determines whether Claude will automatically delegate tasks.
### Strong Trigger Pattern
```yaml --- name: agent-name description: | [Role] specialist. MUST BE USED when [specific triggers]. Use PROACTIVELY for [task category]. Keywords: [trigger words] tools: Read, Write, Edit, Glob, Grep, Bash model: sonnet --- ```
### Weak vs Strong Descriptions
| Weak (won't auto-delegate) | Strong (auto-delegates) | |---------------------------|-------------------------| | "Analyzes screenshots for issues" | "Visual QA specialist. MUST BE USED when analyzing screenshots. Use PROACTIVELY for visual QA." | | "Runs Playwright scripts" | "Playwright specialist. MUST BE USED when running Playwright scripts. Use PROACTIVELY for browser automation." |
**Key phrases**: - "MUST BE USED when..." - "Use PROACTIVELY for..." - Include trigger keywords
### Delegation Mechanisms
1. **Explicit**: `Task tool subagent_type: "agent-name"` - always works 2. **Automatic**: Claude matches task to agent description - requires strong phrasing
**Session restart required** after creating/modifying agents.
## Tool Access Principle
**If an agent doesn't need Bash, don't give it Bash.**
| Agent needs to... | Give tools | Don't give | |-------------------|------------|------------| | Create files only | Read, Write, Edit, Glob, Grep | Bash | | Run scripts/CLIs | Read, Write, Edit, Glob, Grep, Bash | — | | Read/audit only | Read, Glob, Grep | Write, Edit, Bash |
**Why?** Models default to `cat > file << 'EOF'` heredocs instead of Write tool. Each bash command requires approval, causing dozens of prompts per agent run.
### Allowlist Pattern
Instead of restricting Bash, allowlist safe commands in `.claude/settings.json`:
```json { "permissions": { "allow": [ "Write", "Edit", "WebFetch(domain:*)", "Bash(cd *)", "Bash(cp *)", "Bash(mkdir *)", "Bash(ls *)", "Bash(cat *)", "Bash(head *)", "Bash(tail *)", "Bash(grep *)", "Bash(diff *)", "Bash(mv *)", "Bash(touch *)", "Bash(file *)" ] } } ```
## Model Selection (Quality First)
Don't downgrade quality to work around issues - fix root causes instead.
| Model | Use For | |-------|---------| | **Opus** | Creative work (page building, design, content) - quality matters | | **Sonnet** | Most agents - content, code, research (default) | | **Haiku** | Only script runners where quality doesn't matter |
## Memory Limits
### Root Cause Fix (REQUIRED)
Add to `~/.bashrc` or `~/.zshrc`: ```bash export NODE_OPTIONS="--max-old-space-size=16384" ```
Increases Node.js heap from 4GB to 16GB.
### Parallel Limits (Even With Fix)
| Agent Type | Max Parallel | Notes | |------------|--------------|-------| | Any agents | 2-3 | Context accumulates; batch then pause | | Heavy creative (Opus) | 1-2 | Uses more memory |
### Recovery
1. `source ~/.bashrc` or restart terminal 2. `NODE_OPTIONS="--max-old-space-size=16384" claude` 3. Check what files exist, continue from there
## Sub-Agent vs Remote API
**Always prefer Task sub-agents over remote API calls.**
| Aspect | Remote API Call | Task Sub-Agent | |--------|-----------------|----------------| | Tool access | None | Full (Read, Grep, Write, Bash) | | File reading | Must pass all content in prompt | Can read files iteratively | | Cross-referencing | Single context window | Can reason across documents | | Decision quality | Generic suggestions | Specific decisions with rationale | | Output quality | ~100 lines typical | 600+ lines with specifics |
```typescript // ❌ WRONG - Remote API call const response = await fetch('https://api.anthropic.com/v1/messages', {...})
// ✅ CORRECT - Use Task tool // Invoke Task with subagent_type: "general-purpose" ```
## Declarative Over Imperative
Describe **what** to accomplish, not **how** to use tools.
### Wrong (Imperative)
```markdown ### Check for placeholders ```bash grep -r "PLACEHOLDER:" build/*.html ``` ```
### Right (Declarative)
```markdown ### Check for placeholders Search all HTML files in build/ for: - PLACEHOLDER: comments - TODO or TBD markers - Template brackets like [Client Name]
Any match = incomplete content. ```
### What to Include
| Include | Skip | |---------|------| | Task goal and context | Explicit bash/tool commands | | Input file paths | "Use X tool to..." | | Output file paths and format | Step-by-step tool invocations | | Success/failure criteria | Shell pipeline syntax | | Blocking checks (prerequisites) | Micromanaged workflows | | Quality checklists | |
## Self-Documentation Principle
> "Agents that won't have your context must be able to reproduce the behaviour independently."
Every improvement must be encoded into the agent's prompt, not left as implicit knowledge.
### What to Encode
| Discovery | Where to Capture | |-----------|------------------| | Bug fix pattern | Agent's "Corrections" or "Common Issues" section | | Quality requirement | Agent's "Quality Checklist" section | | File path convention | Agent's "Output" section | | Tool usage pattern | Agent's "Process" section | | Blocking prerequisite | Agent's "Blocking Check" section |
### Test: Would a Fresh Agent Succeed?
Before completing any agent improvement: 1. Read the agent prompt as if you have no context 2. Ask: Could a new session follow this and produce the same quality? 3. If no: Add missing instructions, patterns, or references
### Anti-Patterns
| Anti-Pattern | Why It Fails | |--------------|--------------| | "As we discussed earlier..." | No prior context exists | | Relying on files read during dev | Agent may not read same files | | Assuming knowledge from errors | Agent won't see your debugging | | "Just like the home page" | Agent hasn't built home page |
## Agent Prompt Structure
Effective agent prompts include:
```markdown ## Your Role [What the agent does]
## Blocking Check [Prerequisites that must exist]
## Input [What files to read]
## Process [Step-by-step with encoded learnings]
## Output [Exact file paths and formats]
## Quality Checklist [Verification steps including learned gotchas]
## Common Issues [Patterns discovered during development] ```
## Pipeline Agents
When inserting a new agent into a numbered pipeline (e.g., `HTML-01` → `HTML-05` → `HTML-11`):
| Must Update | What | |-------------|------| | New agent | "Workflow Position" diagram + "Next" field | | **Predecessor agent** | Its "Next" field to point to new agent |
**Common bug**: New agent is "orphaned" because predecessor still points to old next agent.
**Verification**: ```bash grep -n "Next:.*→\|Then.*runs next" .claude/agents/*.md ```
## The Sweet Spot
**Best use case**: Tasks that are **repetitive but require judgment**.
Example: Auditing 70 skills manually = tedious. But each audit needs intelligence (check docs, compare versions, decide what to fix). Perfect for parallel agents with clear instructions.
**Not good for**: - Simple tasks (just do them) - Highly creative tasks (need human direction) - Tasks requiring cross-file coordination (agents work independently)
## Effective Prompt Template
``` For each [item]: 1. Read [source file] 2. Verify with [external check - npm view, API call, etc.] 3. Check [authoritative source] 4. Score/evaluate 5. FIX issues found ← Critical instruction ```
**Key elements**: - **"FIX issues found"** - Without this, agents only report. With it, they take action. - **Exact file paths** - Prevents ambiguity - **Output format template** - Ensures consistent, parseable reports - **Batch size ~5 items** - Enough work to be efficient, not so much that failures cascade
## Workflow Pattern
``` 1. ME: Launch 2-3 parallel agents with identical prompt, different item lists 2. AGENTS: Work in parallel (read → verify → check → edit → report) 3. AGENTS: Return structured reports (score, status, fixes applied, files modified) 4. ME: Review changes (git status, spot-check diffs) 5. ME: Commit in batches with meaningful changelog 6. ME: Push and update progress tracking ```
**Why agents don't commit**: Allows human review, batching, and clean commit history.
## Signs a Task Fits This Pattern
**Good fit**: - Same steps repeated for many items - Each item requires judgment (not just transformation) - Items are independent (no cross-item dependencies) - Clear success criteria (score, pass/fail, etc.) - Authoritative source exists to verify against
**Bad fit**: - Items depend on each other's results - Requires creative/subjective decisions - Single complex task (use regular agent instead) - Needs human input mid-process
## Quick Reference
### Agent Frontmatter Template
```yaml --- name: my-agent description: | [Role] specialist. MUST BE USED when [triggers]. Use PROACTIVELY for [task category]. Keywords: [trigger words] tools: Read, Write, Edit, Glob, Grep, Bash model: sonnet --- ```
### Fix Bash Approval Spam
1. Remove Bash from tools if not needed 2. Put critical instructions FIRST (right after frontmatter) 3. Use allowlists in `.claude/settings.json`
### Memory Crash Recovery
```bash export NODE_OPTIONS="--max-old-space-size=16384" source ~/.bashrc && claude ```