name: managing-agents
description: Create, update, and improve Claude Code agent files following Anthropic's official best practices. Use when user mentions "agent", "AGENT.md", "create agent", "update agent", "improve agent", "generate agent", "agent template", "workflow pattern", or wants help with agents. Triggers include "エージェント作成", "コードレビュー用のエージェントを作って", "エージェント改善".
allowed-tools: Read, Write, Edit, Glob, Grep

Managing Claude Code Agents

Create, update, and improve Claude Code agent files following Anthropic's official best practices.

Core Principle: Start simple. "Success isn't about building the most sophisticated system—it's about building the right system for your needs." — Anthropic

When to Use

Automatically invoke when the user:
- Asks to "create an agent" or "make a new agent"
- Wants to "update an agent" or "improve an agent"
- Requests "agent template" or "agent example"
- Wants to "review an agent" or "check agent quality"

Agentic Systems: Workflows vs Agents

Understanding this distinction is critical for designing effective systems.

Decision Guide

Can you predict all steps?

Start with workflows — they provide more control. Add agent autonomy only when results justify the added complexity.

See design-patterns.md for 5 workflow patterns + agent roles.

Quick Reference

Agent File Locations

Simple agent: .claude/agents/agent-name.md (single file)

Complex agent: .claude/agents/agent-name/ (directory)

Minimal Agent Template

---
name: agent-identifier
description: What it does. Use when [triggers].
tools: Read, Grep, Glob
model: sonnet
---

# Agent Name

Brief description.

## Core Responsibilities
- Task 1
- Task 2

## Workflow
1. **Step 1**: Action
2. **Step 2**: Action

## Output Format
[Expected output structure]

Required Fields

name

• Lowercase with hyphens: code-reviewer, test-generator
• Pattern: /^[a-z][a-z0-9-]*$/

description (Critical for Discovery)

Simple Format:

description: Reviews code for quality. Use when user asks "review PR" or "check code".

Rich Format with Examples (Recommended):

description: Use this agent when [task]. Examples:

<example>
Context: [Situation]
user: "[Message]"
assistant: "[Response before invoking]"
<Task tool call to agent-name agent>
</example>

See reference.md for complete examples.

Optional Fields

See reference.md for details.

Agent Design Principles

1. Simplicity First

Start with the simplest solution. Add complexity only when results justify it.

2. Single Responsibility

One clear, focused purpose per agent. Heavy agents (25k+ tokens) create bottlenecks; lightweight agents (<3k tokens) enable fluid orchestration.

3. Creator-Checker Pattern (Evaluator-Optimizer)

Example: nextjs-vibe-coder (Creator) ←→ reviewer (Checker)

4. Minimal Tool Access (ACI)

Agent-Computer Interface — Design tools as carefully as prompts:

See best-practices.md for tool design guidelines.

5. Clear Invocation Triggers

Include phrases like:
- "Use PROACTIVELY when..."
- "Automatically invoke when..."

See design-patterns.md for workflow patterns + agent roles.

Common Agent Types

Creator Agents

Checker Agents

See examples.md for complete templates.

Workflow: Creating an Agent

1. Understand Requirements: Task, triggers, tools needed
2. Choose Format: Single file (<300 lines) or directory
3. Write Frontmatter: name, description, tools, model
4. Write System Prompt: Responsibilities, workflow, output format
5. Create File: .claude/agents/[name].md
6. Test: Try invocation phrases
7. Review: Run claude-config-reviewer agent to validate

Quick Start:

# Simple agent
cat > .claude/agents/my-agent.md << 'EOF'
---
name: my-agent
description: Does X. Use when user asks for Y.
tools: Read, Grep, Glob
---

# My Agent

[System prompt...]
EOF

See reference.md for detailed workflow.

Workflow: Updating an Agent

1. Read Current Agent: Load existing file
2. Identify Issues: Vague instructions, missing workflow
3. Apply Changes: Use Edit tool
4. Verify: Check against quality checklist
5. Review: Run claude-config-reviewer agent to validate

See reference.md for evaluation criteria.

Progressive Disclosure (Complex Agents)

For agents exceeding 300 lines, use directory structure:

Key Rules:
- AGENT.md under 500 lines
- References one level deep only
- Include table of contents in long files

See reference.md for complete specification.

Built-in Agents

Resumable Agents

// Resume previous session
Task({
  resume: "previous-agent-id",
  prompt: "Continue from where we left off"
})

Common Mistakes

Related Files

• reference.md - Frontmatter schema, validation rules, directory format
• examples.md - Complete agent templates (9 types)
• design-patterns.md - 5 agent design patterns
• best-practices.md - Advanced patterns, anti-patterns

Storage Locations