Agent Creator

Overview

Creates subagent definitions for Claude Code. Subagents are specialized assistants that Claude can invoke for specific tasks.

When to use: User requests an agent, wants to add specialized subagent to plugin, or needs agent structure guidance.

References: Consult plugins/meta/claude-docs/skills/official-docs/reference/plugins-reference.md and plugins/meta/claude-docs/skills/official-docs/reference/sub-agents.md for specifications.

CRITICAL: Two Types of Agents

Claude Code has two distinct agent types with different requirements:

Plugin Agents (plugins/*/agents/)

Purpose: Agents distributed via plugins for team/community use

Required frontmatter fields:

• description (required) - What this agent specializes in
• capabilities (required) - Array of specific capabilities

Location: plugins/<category>/<plugin-name>/agents/agent-name.md

Example:

---
description: Expert code reviewer validating security and quality
capabilities: ["vulnerability detection", "code quality review", "best practices"]
---

User/Project Agents (.claude/agents/)

Purpose: Personal agents for individual workflows

Required frontmatter fields:

• name (required) - Agent identifier
• description (required) - When to invoke this agent
• tools (optional) - Comma-separated tool list
• model (optional) - Model alias (sonnet, opus, haiku)

Location: .claude/agents/agent-name.md or ~/.claude/agents/agent-name.md

Example:

---
name: code-reviewer
description: Expert code review. Use after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

Key difference: User agents have name field and system prompt. Plugin agents have capabilities array and documentation.

Agent Structure Requirements (Plugin Agents)

Every plugin agent MUST include:

1. Frontmatter with description and capabilities array
2. Agent title as h1
3. Capabilities section explaining what agent does
4. When to Use section with invocation criteria
5. Context and Examples with concrete scenarios
6. Located in agents/agent-name.md within plugin

Creation Process

Step 0: Determine Agent Type

Ask the user:

• Is this for a plugin (team/community distribution)?
• Or for personal use (.claude/agents/)?

If personal use: Use user agent format with name, description, system prompt. See plugins/meta/claude-docs/skills/official-docs/reference/sub-agents.md for examples.

If plugin: Continue with plugin agent format below.

Step 1: Define Agent Purpose

Ask the user:

• What specialized task does this agent handle?
• What capabilities distinguish it from other agents?
• When should Claude invoke this vs doing work directly?

Step 2: Determine Agent Name

Create descriptive kebab-case name:

• "security review" → security-reviewer
• "performance testing" → performance-tester
• "API documentation" → api-documenter

Step 3: List Capabilities

Identify 3-5 specific capabilities:

• Concrete actions the agent performs
• Specialized knowledge it applies
• Outputs it generates

Step 4: Structure the Agent

Use this template:

---
description: One-line agent description
capabilities: ["capability-1", "capability-2", "capability-3"]
---

# Agent Name

Detailed description of agent's role and expertise.

## Capabilities

- **Capability 1**: What this enables
- **Capability 2**: What this enables
- **Capability 3**: What this enables

## When to Use This Agent

Claude should invoke when:
- Specific condition 1
- Specific condition 2
- Specific condition 3

## Context and Examples

**Example 1: Scenario Name**

User requests: "Help with X"
Agent provides: Specific assistance using capabilities

**Example 2: Another Scenario**

When Y happens, agent does Z.

Step 5: Verify Against Official Docs

For plugin agents: Check plugins/meta/claude-docs/skills/official-docs/reference/plugins-reference.md (requires capabilities array).

For user agents: Check plugins/meta/claude-docs/skills/official-docs/reference/sub-agents.md (requires name field).

Key Principles

• Specialization: Agents should have focused expertise
• Clear Invocation: Claude must know when to use this agent
• Concrete Capabilities: List specific things agent can do
• Examples: Show real scenarios where agent helps

Examples

Example 1: Security Reviewer Agent

User: "Create an agent for security reviews"

Process:

1. Purpose: Reviews code for security vulnerabilities
2. Name: security-reviewer
3. Capabilities: ["vulnerability detection", "security best practices", "threat modeling"]
4. Structure: Include when to invoke, examples of security issues
5. Create: agents/security-reviewer.md

Output: Agent that Claude invokes for security-related code review

Example 2: Performance Tester Agent

User: "I need an agent for performance testing"

Process:

1. Purpose: Designs and analyzes performance tests
2. Name: performance-tester
3. Capabilities: ["load testing", "benchmark design", "performance analysis"]
4. Structure: When to use for optimization vs testing
5. Create: agents/performance-tester.md

Output: Agent that Claude invokes for performance concerns