/agent-design

Agent Creator

This skill provides guidance for creating effective Claude Code agents.

About Agents

Agents are Markdown files with YAML frontmatter that configure Claude Code with specialized behavior. They can be used in two ways:

1. Main Agent (claude --agent name) - Starts Claude Code as this persona
2. Subagent (Task tool) - Spawns a focused worker that reports back

Unlike skills (which inject knowledge into context), agents fundamentally change who Claude is for that session - the system prompt, available tools, and even the model.

When to Create an Agent

Use Case	Create Agent?	Alternative
Specialized persona with restricted tools	Yes	-
Domain expert needing specific MCPs/skills	Yes	-
Cost optimization (haiku for simple tasks)	Yes	-
Orchestrator that delegates to sub-agents	Yes	-
Adding domain knowledge to context	No	Create a skill
One-off task instructions	No	Direct prompting
Reusable scripts/assets	No	Create a skill

Agent vs Skill Decision

• Agent: Changes who Claude is (persona, tools, model)
• Skill: Changes what Claude knows (knowledge, procedures, scripts)

Agents can load skills. Skills cannot become agents.

Agent Anatomy

File Location

Agents are stored as .md files in:

• ~/.claude/agents/ - User-level (global, all projects)
• .claude/agents/ - Project-level (repo-specific, higher precedence)

Required Structure

---
description: "When to use this agent. Be specific about triggers."
---

System prompt content goes here.

All Configuration Options

Field	Required	Type	Description
name	Yes	string	Unique ID (lowercase, hyphens only)
description	Yes	string	When/why to invoke this agent
tools	No	list	Restrict to specific tools only
model	No	string	haiku, sonnet, opus, or omit to inherit
permissionMode	No	string	default, acceptEdits, plan, bypassPermissions
skills	No	list	Auto-load specific skills

Tool Restriction

Omitting tools grants all available tools. Specifying it creates a whitelist:

tools:
  - Read
  - Grep
  - Glob

Common tools: Read, Write, Edit, Glob, Grep, Bash, Task, WebSearch, WebFetch, TodoWrite

See ${CLAUDE_PLUGIN_ROOT}/references/tool-catalog.md for the complete catalog with use cases.

Agent Creation Process

Step 1: Define the Agent's Purpose

Before writing, answer:

1. What is this agent's specialty? (one clear focus)
2. When should it be invoked? (specific triggers)
3. What tools does it need? (minimum viable set)
4. What model fits the task? (haiku=fast/cheap, sonnet=balanced, opus=complex)
5. What MCPs or skills should it load?

Step 2: Initialize the Agent

Run the initialization script to scaffold the agent file:

python ~/.claude/skills/agent-creator/scripts/init_agent.py <agent-name> [--path <directory>]

Default path is ~/.claude/agents/ (user-level). Use .claude/agents/ for project-level.

Step 3: Write the System Prompt

The system prompt (Markdown body after frontmatter) defines the agent's behavior. Follow Opus 4.5 prompting best practices from ${CLAUDE_PLUGIN_ROOT}/references/opus-prompting.md.

System Prompt Structure

---
description: "..."
---

[Role statement - who this agent is]

## Capabilities
[What this agent can do]

## Guidelines
[How to approach tasks]

## Workflow
[Step-by-step process if applicable]

Writing Style

• Use imperative form: "Analyze the code" not "You should analyze the code"
• Be explicit and specific: State exactly what to do
• Add context for why: Explain reasoning behind guidelines
• Include concrete examples: Show expected behavior
• Keep it focused: One clear specialty, not a generalist

Step 4: Configure Tools and Model

Match tools to the agent's purpose:

Agent Type	Recommended Tools	Model
Researcher	Read, Grep, Glob, WebSearch, WebFetch	sonnet
Code Reviewer	Read, Grep, Glob, Bash	sonnet
Writer/Editor	Read, Write, Edit	sonnet
Quick Search	Grep, Glob, Read	haiku
Complex Analysis	Read, Grep, Glob, Task	opus
Orchestrator	Task, Read, TodoWrite	opus

Step 5: Add MCP/Skill Integrations

For agents that need external capabilities:

skills:
  - ui-styling
  - docs-seeker

Reference skills in the system prompt:

## Available Skills

Use the `ui-styling` skill for shadcn components and Tailwind.
Use the `docs-seeker` skill for finding library documentation.

For MCP tools, mention them explicitly in the system prompt so the agent knows they're available.

Step 6: Test and Iterate

1. Test as main agent: claude --agent your-agent
2. Test as subagent: Use Task tool to spawn it
3. Verify tool restrictions: Ensure it only uses allowed tools
4. Check persona consistency: Does it maintain character?
5. Validate triggers: Does the description accurately predict usage?

Opus 4.5 Prompting Guidelines

Claude Opus 4.5 has specific characteristics that affect agent design. See ${CLAUDE_PLUGIN_ROOT}/references/opus-prompting.md for full details.

Key Points

1. Dial back aggressive language - Replace "CRITICAL/MUST" with normal phrasing
2. Avoid "think" - Use "consider", "evaluate", "reflect" when extended thinking is off
3. Be explicit about action - "Implement changes" vs "suggest changes"
4. Include anti-over-engineering guidance - Opus tends to add unnecessary abstractions
5. Examples matter - Opus follows examples precisely, ensure they're correct
6. Parallel tool calling - Explicitly encourage when tools are independent

Anti-Over-Engineering Snippet

Include this in agents that write code:

Avoid over-engineering. Only make changes directly requested or clearly necessary.
Keep solutions simple and focused. Do not add features, refactor code, or make
improvements beyond what was asked.

Agent Patterns

See ${CLAUDE_PLUGIN_ROOT}/references/agent-patterns.md for common archetypes:

• Researcher - Read-only exploration and analysis
• Specialist - Domain expert with focused tools
• Reviewer - Code/content review without editing
• Builder - Focused creation with write access
• Orchestrator - Delegates to sub-agents
• Quick Responder - Fast, cheap responses with haiku

Validation Checklist

Before finalizing an agent:

• Name is lowercase with hyphens only
• Description clearly states when to use the agent
• Tools are minimal but sufficient for the task
• Model matches complexity needs (haiku/sonnet/opus)
• System prompt uses imperative form
• No "CRITICAL/MUST" aggressive language
• Includes anti-over-engineering guidance if writes code
• Examples in prompt are accurate and helpful
• Tested as both main agent and subagent