Agent Creator

Create specialized subagents for Claude Code plugins with proper markdown format, YAML frontmatter, and detailed system prompts.

When to Use This Skill

Use when:

• Creating new subagents for plugins
• User requests "create an agent" or "add an agent"
• Building specialized AI assistants for specific tasks
• Need task-specific configurations with custom prompts

What Subagents Are

Subagents are specialized AI assistants that:

• Have specific purposes and expertise areas
• Use separate context windows from main conversation
• Can be configured with specific tools
• Include custom system prompts guiding behavior
• Are invoked automatically when tasks match their expertise

Agent File Structure

Agents are markdown files with YAML frontmatter:

```yaml
---
name: agent-name
description: What this agent does and when to invoke it
tools: Tool1, Tool2, Tool3  # Optional
model: sonnet  # Optional: sonnet, opus, haiku, or 'inherit'
---
```

# Agent Name

Your agent's system prompt goes here...

Instructions

Step 1: Define Agent Purpose

Gather agent requirements:

• Role: What is the agent's specialized function?
• Expertise: What domain/task does it excel at?
• When to invoke: What triggers should activate it?
• Tools needed: Which tools are required?
• Model preference: Which model should it use?

Step 2: Create Agent File

Create markdown file in agents/ directory:

Filename: <agent-name>.md (kebab-case)

Location:

• Plugin agents: <plugin-root>/agents/
• Project agents: .claude/agents/
• User agents: ~/.claude/agents/

Step 3: Write YAML Frontmatter

---
name: agent-name
description: Brief description of agent's purpose and when to invoke
tools: Read, Write, Edit, Bash, Grep, Glob  # Optional
model: sonnet  # Optional
---

Required fields:

• name: Unique identifier (lowercase, hyphens)
• description: Natural language description of purpose

Optional fields:

• tools: Comma-separated list of allowed tools (inherits all if omitted)
• model: sonnet, opus, haiku, or 'inherit' (defaults to configured subagent model)

Step 4: Write System Prompt

After frontmatter, write the agent's system prompt:

# Agent Name

You are a [role description].

## Your Role

[Detailed explanation of the agent's role and expertise]

## Guidelines

1. [Specific instruction]
2. [Best practice]
3. [Constraint or rule]

## When to Invoke

[Description of when Claude should use this agent]

## Workflow

1. [Step-by-step process]
2. [What to do in different scenarios]
3. [How to handle edge cases]

## Examples

- [Example task 1]
- [Example task 2]

Step 5: Configure Tools (Optional)

Specify tools if agent needs restricted access:

Read-only agent:

tools: Read, Grep, Glob

Code editor agent:

tools: Read, Write, Edit, Grep, Glob, Bash

Full access (default): Omit tools field to inherit all tools.

Step 6: Choose Model (Optional)

Select appropriate model for the agent:

Fast, cost-effective (Haiku):

model: haiku

Balanced (Sonnet - default):

model: sonnet

Maximum capability (Opus):

model: opus

Match main conversation:

model: 'inherit'

Frontmatter Field Reference

name (required)

Rules:

• Lowercase letters, numbers, hyphens only
• Unique identifier for the agent
• Used in invocation and management

Examples:

• code-reviewer
• test-runner
• security-analyst

description (required)

Purpose: Helps Claude decide when to invoke the agent

Best practices:

• Be specific about agent's role
• Include trigger scenarios
• Mention task types
• Include keywords users might say

Examples:

✓ Good:

description: Expert code reviewer for security, performance, and best practices. Use immediately after writing or modifying code, or when reviewing pull requests.

✗ Poor:

description: Helps with code

tools (optional)

Purpose: Restricts which tools the agent can use

When to specify:

• Agent should have limited access
• Security-sensitive workflows
• Read-only operations
• Specific tool combinations needed

Available tools:

• Read, Write, Edit - File operations
• Grep, Glob - File search
• Bash - Shell commands
• Task - Subagent invocation (usually not included)
• WebFetch, WebSearch - Web operations
• MCP tools - From connected MCP servers

model (optional)

Options:

• sonnet - Balanced (default for subagents)
• opus - Most capable
• haiku - Fast and cost-effective
• 'inherit' - Use main conversation's model

When to specify:

• Need faster/cheaper responses (haiku)
• Need maximum capability (opus)
• Want consistent model with main conversation (inherit)

Example Agents

Code Reviewer

```yaml
---
name: code-reviewer
description: Expert code reviewer ensuring high standards. Use immediately after writing or modifying code, or for pull request reviews.
tools: Read, Grep, Glob, Bash
model: inherit
---
```

# Code Reviewer

You are a senior code reviewer ensuring high standards of code quality and security.

## Review Process

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

## Review Checklist

- Code is simple and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

## Feedback Organization

Provide feedback organized by priority:
- **Critical issues** (must fix)
- **Warnings** (should fix)
- **Suggestions** (consider improving)

Include specific examples of how to fix issues.

Debugger

```yaml
---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---
```

# Debugger

You are an expert debugger specializing in root cause analysis.

## Debugging Process

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

## Analysis Steps

- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

## Output Format

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not just symptoms.

Data Scientist

```yaml
---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---
```

# Data Scientist

You are a data scientist specializing in SQL and BigQuery analysis.

## Workflow

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

## Key Practices

- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

## Output

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

Best Practices

1. Design focused agents: Single, clear responsibility
2. Write detailed prompts: Specific instructions and examples
3. Limit tool access: Only grant necessary tools
4. Test thoroughly: Verify agent triggers correctly
5. Version control: Commit agents to share with team
6. Use proactive language: "use PROACTIVELY" or "MUST BE USED" in descriptions

Troubleshooting

Agent doesn't trigger:

• Make description more specific
• Add trigger keywords
• Test with explicit invocation
• Check agent appears in /agents

Wrong tools available:

• Review tools field in frontmatter
• Verify tools list is comma-separated
• Check for typos in tool names

Agent uses wrong model:

• Check model field in frontmatter
• Verify model name is correct
• Ensure quotes around 'inherit' if using

Reference

For complete agent documentation, see references/agent-format.md.