Agent Creator

Guide for creating effective Claude Code agents. An agent is a markdown file with YAML frontmatter stored in .claude/agents/. The frontmatter configures behavior; the markdown body is the system prompt.

Agent File Structure

---
name: my-agent
description: What this agent does and when to use it.
tools: [Read, Grep, Glob]
model: sonnet
permissionMode: dontAsk
maxTurns: 15
---

# Agent System Prompt

Instructions for the agent go here. Write like you're briefing a colleague.
The more specific and structured, the more consistent the behavior.

Frontmatter Fields

Required

Optional

Tools Reference

Read-only set: [Read, Grep, Glob] — use for reviewers, auditors, explorers. Standard write set: [Read, Write, Edit, Bash, Grep, Glob] — use for implementers.

No nesting: Agents cannot spawn other agents. Even if Task is listed, it has no effect.

Permission Modes

Model Selection

Use Sonnet or Opus for sensitive code: auth, payments, database ops, crypto — accuracy matters for security.

Where to Save

Agents load at session start. If created mid-session, restart or use /agents to reload.

Agent Lifecycle

1. Spawn — Fresh context with: agent's system prompt + CLAUDE.md + environment details. Parent summarizes relevant context in the task prompt (lossy).
2. Execute — Works independently using only its granted tools.
3. Return — Results come back as a summary, not full output.
4. Resume (optional) — Pass agent's ID to continue where it left off with full history intact.

What agents receive

• Their custom system prompt (markdown body)
• CLAUDE.md project instructions
• Basic environment details (working directory, platform)
• Preloaded skills (only if listed in skills field)

What agents do NOT receive

• Parent conversation history
• Parent skills (must be explicit)
• Full Claude Code system prompt (agents get their own simpler prompt)

Context & storage

• Own context window — verbose tool output stays in agent's window, not yours
• Compaction — at ~95% capacity, older messages compressed. Put critical rules in CLAUDE.md (reloaded after compaction)
• Transcripts — saved as ~/.claude/projects/<hash>/agent-<agentId>.jsonl. Auto-removed after 30 days.

Invocation

Foreground: 1 agent → conversation pauses until done. Background: Multiple agents → run concurrently in parallel. Background agents cannot use MCP tools or ask questions.

Built-in Agents

Disable a built-in: { "permissions": { "deny": ["Task(Explore)"] } } in settings.

Best Practices

1. Minimal tools — [Read, Grep, Glob] can't delete files or run commands. If prompt injection tricks it, damage is contained to reading.
2. Specific descriptions — "Handle code tasks" matches everything poorly. "Review TypeScript for security vulnerabilities in the auth module" activates reliably.
3. Set maxTurns — Without limit, confused agent loops indefinitely burning tokens. Code reviewer rarely needs >15 turns.
4. dontAsk for read-only — Blocks actions needing approval. Second safety layer beyond tool restrictions.
5. Sonnet/Opus for sensitive code — Larger models are harder to prompt-inject. Haiku follows instructions more literally.
6. Check into version control — Agents are code. PR reviews catch permission escalation and prompt regressions.
7. Haiku for parallel research — 10 Haiku agents cost ≈ 1 Sonnet. Finish much faster for simple file lookups.
8. Start restrictive, expand later — Easier to grant access than recover from a security incident.
9. Store critical rules in CLAUDE.md — Survives compaction. Agent system prompt can be lost at ~95% capacity.
10. Provide verification criteria — "Write validateEmail, test: user@example.com → true, invalid → false. Run tests after." gives the agent a feedback loop.

Common Mistakes

1. Swiss Army knife agent — One agent with all tools and vague description. Never activates reliably, can't be specialized, security liability.
2. Subagents for implementation — They do NOT inherit conversation history. Use for research/information gathering; implement in main session.
3. Parallel agents editing same files — Last-write-wins race condition. Define explicit file ownership.
4. Expecting conversation inheritance — Agents start fresh. Include ALL necessary context in the task prompt.
5. Not reviewing test modifications — Agents sometimes change assertions to match incorrect code. Always review test file changes.
6. Correction loops — After 2 failed attempts, start fresh. /clear + better prompt is cheaper than noise accumulation.
7. Over-parallelizing — 5 agents for a single-domain feature wastes tokens. Match parallelism to task complexity.

Creation Workflow

1. Identify the task — What specific job does this agent do? Be narrow.
2. Choose tools — Start with minimum needed. Read-only if possible.
3. Choose model — Haiku for simple lookups, Sonnet for standard work, Opus for critical reasoning.
4. Set permissions — dontAsk for read-only agents, default for writers.
5. Set maxTurns — Estimate reasonable turns for the task. Add small buffer.
6. Write description — Specific enough that Claude activates it for the right tasks and ignores it for others.
7. Write system prompt — Tell the agent how to do its job: what to focus on, output format, what to avoid, domain rules.
8. Add memory (optional) — Only if agent runs repeatedly across sessions. See references/memory-and-hooks.md.
9. Add hooks (optional) — Auto-format, auto-lint, cleanup. See references/memory-and-hooks.md.
10. Add skills (optional) — Explicitly list any skills the agent needs.
11. Save to .claude/agents/ and commit to Git.

Advanced Topics

• Persistent memory, hooks, and skills integration: See references/memory-and-hooks.md
• Common agent patterns, orchestration, and agent teams: See references/patterns-and-teams.md