Agent Expert Agent

Your meta-agent for designing, building, and optimizing specialized Claude Code agents — covering agent architecture, prompt engineering, tool integration, domain modeling, and agent composition.

When to Use This Agent

Choose Agent Expert Agent when:

• Designing new specialized agents for specific domains or workflows
• Optimizing existing agent prompts for better performance and accuracy
• Creating agent systems that compose multiple specialized agents
• Modeling domain knowledge for agent consumption
• Debugging agent behavior issues (hallucination, tool misuse, scope drift)

Consider alternatives when:

• You need a specific domain agent — use that domain's agent directly
• You need general coding assistance — use a general-purpose coding agent
• You need infrastructure automation — use a DevOps or Terraform agent

Quick Start

Copy
# .claude/agents/agent-expert.yml
name: Agent Expert Agent
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Meta-agent for designing, building, and optimizing specialized Claude Code agents

Example invocation:

claude "Design an agent for automated database migration management — it should analyze schema changes, generate migration files, validate data integrity, and handle rollbacks"

Core Concepts

Agent Design Components

Component	Purpose	Example
System Prompt	Define agent identity and capabilities	"You are a database migration expert..."
Tool Selection	Which tools the agent can use	Read, Write, Bash, Grep
Domain Model	Knowledge the agent needs	Migration patterns, SQL dialects, ORMs
Guard Rails	Constraints on agent behavior	"Never drop tables without confirmation"
Output Format	How the agent presents results	Structured reports, code changes, plans
Error Handling	How the agent handles failures	Retry strategies, fallback behavior

Agent Architecture Patterns

Single Agent
  └─ One agent handles everything (simple tasks)

Pipeline Agent
  └─ Agent A → Agent B → Agent C (sequential processing)

Orchestrator + Workers
  └─ Manager agent delegates to specialist agents

Parallel Agents
  └─ Multiple agents work simultaneously on independent subtasks

Hierarchical Agents
  └─ Parent agents supervise child agents with escalation paths

Configuration

Parameter	Description	Default
agent_type	Architecture pattern (single, pipeline, orchestrator)	single
model	Underlying model (claude-sonnet, claude-opus)	claude-sonnet
tool_set	Available tools for the designed agent	project-appropriate
domain	Target domain for the agent	specified per design
safety_level	Guard rail strictness (permissive, balanced, strict)	balanced

Best Practices

1. Define the agent's scope explicitly with "when to use" and "when NOT to use" sections. An agent that tries to do everything does nothing well. Clear scope boundaries prevent scope drift and help users choose the right agent for their task.

2. Start with the minimum necessary tool set. Give agents only the tools they need. An agent that can Write files but shouldn't modify code is better designed with Read-only access. Unnecessary tool access increases the risk of unintended side effects.

3. Include concrete examples in the system prompt. Show the agent examples of good inputs and expected outputs. "Here's a typical request and how you should respond" is more effective than abstract instructions. Examples ground the agent's behavior better than rules alone.

4. Build guard rails for destructive operations. Any agent that can modify files, run commands, or interact with external services needs explicit safety constraints. "Always preview changes before applying," "Never delete without confirmation," and "Ask before modifying files outside the project directory."

5. Test agents against edge cases, not just happy paths. Design test scenarios for ambiguous requests, missing context, conflicting instructions, and error conditions. An agent that works perfectly on clear requests but fails on real-world ambiguity isn't production-ready.

Common Issues

Agent hallucinates domain-specific knowledge. When the agent lacks deep domain knowledge, it fills gaps with plausible but incorrect information. Ground the agent with reference documentation, require it to verify claims against source code or docs, and include "say 'I don't know' rather than guessing" in the prompt.

Agent uses tools inappropriately or in wrong order. Without clear tool-use guidance, agents may read files they don't need, edit files prematurely, or skip verification steps. Add explicit workflows in the system prompt: "1. Read the relevant files, 2. Analyze the problem, 3. Propose changes, 4. Implement after confirmation."

Agent scope drifts beyond its intended domain. Users ask agents to do things outside their expertise, and the agent tries to help rather than declining. Include explicit scope boundaries: "You are a migration expert. For questions about application architecture, recommend using the architecture agent instead."