agent-improver

Create and improve agents.

Triggers

• "create an agent for X"
• "build me an agent"
• "I need an agent that does Y"
• "make a code review agent"
• "create a testing agent"
• "improve my agent"
• "list agents"
• "what agents do I have"

Create Agent

Write directly to .claude/agents/{name}.md:

---
name: agent-name
description: >-
  What this agent does and when Claude should delegate to it.
  Be specific. Include "Use proactively" if it should auto-trigger.
tools: Read, Grep, Glob, Bash
---

You are [role description]. [System prompt for the agent.]

When invoked:
1. First step
2. Second step
3. Third step

## Output Format

[Expected output structure]

Frontmatter Reference

Field	Required	Purpose
name	Yes	Unique ID, lowercase + hyphens
description	Yes	When Claude should delegate. Include "Use proactively" for auto-trigger
tools	No	Allowlist of tools. Inherits all if omitted
disallowedTools	No	Denylist (removed from inherited/specified set)
model	No	sonnet, opus, haiku, inherit, or full model ID
permissionMode	No	default, acceptEdits, dontAsk, bypassPermissions, plan
maxTurns	No	Max agentic turns before auto-stop
skills	No	Skills preloaded into agent context (full content injected)
mcpServers	No	MCP servers: string reference or inline definition
hooks	No	PreToolUse/PostToolUse/Stop hooks scoped to this agent
memory	No	user, project, or local
background	No	true = always run as background task
effort	No	low, medium, high, max
isolation	No	worktree = isolated git worktree copy

Agent Scope

Location	Scope	Priority
--agents CLI flag	Current session only	1 (highest)
.claude/agents/	Current project	2
~/.claude/agents/	All your projects	3
Plugin agents/ dir	Where plugin enabled	4 (lowest)

Higher priority wins when names collide.

Model Selection Guide

Model	Best for
haiku	Fast, cheap: exploration, search, simple tasks
sonnet	Balanced: code review, analysis, moderate complexity
opus	Most capable: complex reasoning, architecture, planning
inherit	Same as main conversation (default)

Memory Scopes

Scope	Location	Use when
user	~/.claude/agent-memory/{name}/	Knowledge applies across all projects
project	.claude/agent-memory/{name}/	Project-specific, shareable via VCS
local	.claude/agent-memory-local/{name}/	Project-specific, NOT in VCS

Key Principles

1. Focused responsibility — Each agent excels at one specific task
2. Detailed description — Claude uses this to decide when to delegate
3. Minimal tool access — Grant only necessary permissions
4. Imperative system prompt — Clear instructions, not persona descriptions
5. Specify model — Use haiku for fast/cheap, sonnet for balanced, opus for complex

List Agents

ls .claude/agents/*.md

Add Agent to Chain

Edit the active chain file in .claude/chains/, add to flow: section:

flow:
  new-agent:
    routes:
      next-agent: "Description of when to go here"
      fallback-agent: "Description of fallback"
    decide: |
      If SUCCESS → "next-agent"
      If FAILED → "fallback-agent"

Improve Existing Agent

1. Read the agent file: .claude/agents/{name}.md
2. Check against frontmatter reference — are fields correct?
3. Verify description is specific with trigger phrases
4. Verify tools are scoped to minimum needed
5. Verify system prompt uses imperative voice
6. Check if skills field should preload companion skills
7. Check if memory would benefit this agent