Add Agent

Create a new sub-agent file with proper frontmatter and structure.

Arguments

• $1 (required): Agent name in kebab-case (e.g., code-reviewer)
• $2 (optional): Description in quotes (e.g., "Reviews code for quality")
• --plugin=<plugin-name> (optional): Specify which plugin to add the agent to

Usage:

# From within a plugin directory, with description
/plugin-development:add-agent code-reviewer "Reviews code for quality, security, and best practices"

# Without description (uses default)
/plugin-development:add-agent code-reviewer

# From marketplace root, specifying plugin
/plugin-development:add-agent code-reviewer "Reviews code for quality, security, and best practices" --plugin=plugin-development

Prerequisites

• Must be run from either:
  • A plugin root directory (containing .claude-plugin/plugin.json), OR
  • A marketplace root directory (containing .claude-plugin/marketplace.json)
• agents/ directory will be created if needed

Instructions

Validation

IMPORTANT: When running test commands for validation (checking directories, files, etc.), use require_user_approval: false since these are read-only checks.

1. Detect context and target plugin (output thoughts during this process):

   a. Check if we're in a plugin directory:

   • Look for .claude-plugin/plugin.json in current directory
   • Output: "Checking for plugin directory..."
   • If found:
     • Output: "Found plugin.json - using current directory as target plugin"
     • Use current directory as target plugin
   • If not found:
     • Output: "Not in a plugin directory, checking for marketplace..."

   b. If not in plugin directory, check if we're in marketplace root:

   • Look for .claude-plugin/marketplace.json in current directory
   • If found:
     • Output: "Found marketplace.json - this is a marketplace root"
     • This is a marketplace root
   • If not found:
     • Output: "Error: Neither plugin.json nor marketplace.json found"
     • Show error and exit

   c. If in marketplace root, determine target plugin:

   • Check if --plugin=<name> argument was provided
   • If yes:
     • Output: "Using plugin specified via --plugin argument: <name>"
     • Use specified plugin name
   • If no:
     • Output: "No --plugin argument provided, discovering available plugins..."
     • Discover available plugins and prompt user

   d. Discover available plugins (when in marketplace root without --plugin):

   • Output: "Reading marketplace.json..."
   • Read .claude-plugin/marketplace.json
   • Extract plugin names and sources from plugins array
   • Output: "Found [N] plugin(s) in marketplace"
   • Alternative: List directories in plugins/ directory
   • Present list to user: "Which plugin should I add the agent to?"
   • Options format: 1. plugin-name-1 (description), 2. plugin-name-2 (description), etc.
   • Wait for user selection
   • Output: "Selected plugin: <plugin-name>"

   e. Validate target plugin exists:

   • Output: "Validating plugin '<plugin-name>' exists..."
   • If plugin specified/selected, verify plugins/<plugin-name>/.claude-plugin/plugin.json exists
   • If found:
     • Output: "Plugin '<plugin-name>' validated successfully"
   • If not found:
     • Output: "Error: Plugin '<plugin-name>' not found"
     • Show error: "Plugin '<plugin-name>' not found. Available plugins: [list]"

   f. If neither plugin.json nor marketplace.json found:

   • Show error: "Not in a plugin or marketplace directory. Please run from a plugin root or marketplace root."

2. Validate arguments:

   • $1 (agent name): Not empty, kebab-case format (lowercase with hyphens), no spaces or special characters
   • $2 (description): Optional. If not provided, use default: "Specialized agent for $1 tasks"

3. Set working directory:

   • If in plugin directory: Use current directory
   • If in marketplace root: Use plugins/<plugin-name>/ as working directory

Create Agent File

Note: All paths below are relative to the target plugin directory (determined in validation step).

1. Ensure agents/ directory exists in target plugin:
   • Check if <plugin-dir>/agents/ directory exists
   • If it doesn't exist, create it (use require_user_approval: false for directory creation)
2. Create <plugin-dir>/agents/$1.md with this template:

---
name: $1
description: $2
tools: Read, Grep, Glob, Bash
model: inherit
permissionMode: default
---

# $1 Agent

[Brief introduction explaining the agent's purpose and specialization]

## Purpose

[Detailed description of what this agent does and why it exists]

## What This Agent Does

This agent specializes in:
- [Specialization 1]
- [Specialization 2]
- [Specialization 3]

## Capabilities

1. **Capability 1**: [Description of first capability]
2. **Capability 2**: [Description of second capability]
3. **Capability 3**: [Description of third capability]

## When to Use This Agent

Invoke this agent when:
- [Scenario 1: Complex multi-file analysis needed]
- [Scenario 2: Deep domain expertise required]
- [Scenario 3: Task needs separate context window]

**Do not use** for:
- [What this agent doesn't handle]
- [Tasks better suited for commands or Skills]

## How It Proceeds

The agent follows this workflow:

1. **Gather Context**: [What files/information it reads]
2. **Analyze**: [How it evaluates the situation]
3. **Identify Issues**: [What it looks for]
4. **Formulate Recommendations**: [What guidance it provides]
5. **Report Back**: [What it returns to main conversation]

## Output Format

The agent returns a structured report:

### Critical Issues
- [Issues that must be fixed]

### Warnings
- [Issues that should be fixed]

### Suggestions
- [Nice-to-have improvements]

### Summary
- [Overall assessment and next steps]

## Tool Access

This agent has access to:
- Read: For examining files
- Grep: For searching content
- Glob: For finding files
- [Other tools as needed]

It does **not** modify files directly; instead, it proposes changes for the main conversation to execute.

## Example Invocation

**From main conversation**:

/agents $1

or via Task tool:

Use the $1 agent to [specific task]

## Notes

- Agents operate in a **separate context window**
- Results are returned as a single message
- Use for complex, multi-step analysis tasks
- Keep scope focused to 1-3 specific capabilities

Update plugin.json (if needed)

IMPORTANT: Only needed if using custom (non-standard) paths.

• Standard setup (agents in agents/ directory): No changes to plugin.json needed
• Custom paths: Add "agents": ["./agents/$1.md"] (or update existing agents array)

Provide Feedback

After creating the agent:

✓ Created <plugin-name>/agents/$1.md

Plugin: <plugin-name>
Agent: $1
Description: $2

Next steps:
1. Edit <plugin-name>/agents/$1.md with specific instructions
2. Key frontmatter fields:
   - name: Unique agent identifier (lowercase with hyphens)
   - description: What the agent does and when to invoke (shows in /agents list)
   - tools: CSV list of tools (optional, inherits all if omitted)
   - model: sonnet, opus, haiku, or inherit (optional)
   - permissionMode: default, acceptEdits, bypassPermissions, or plan (optional)
   - skills: CSV list of skills to auto-load (optional)
3. Define clear workflow steps
4. Specify what the agent returns
5. Test with /plugin-development:test-local

Agent will be invoked as: /agents $1
Or via Task tool in main conversation.

Examples

Example 1: From Plugin Directory

Context: Currently in /path/to/marketplace/plugins/plugin-development/

Input:

/plugin-development:add-agent code-reviewer "Reviews code for quality, security, and best practices"

Arguments:

• $1 = code-reviewer
• $2 = Reviews code for quality, security, and best practices

Process:

1. Detects .claude-plugin/plugin.json in current directory
2. Uses current directory as target plugin
3. Creates agents/ directory if needed
4. Creates agents/code-reviewer.md

Result:

• Creates agents/code-reviewer.md with template
• Frontmatter description: "Reviews code for quality, security, and best practices"
• Ready to customize with specific review criteria

Example 2: From Marketplace Root with --plugin

Context: Currently in /path/to/marketplace/ (marketplace root)

Input:

/plugin-development:add-agent code-reviewer "Reviews code for quality, security, and best practices" --plugin=plugin-development

Process:

1. Detects .claude-plugin/marketplace.json in current directory
2. Extracts --plugin=plugin-development from arguments
3. Validates plugins/plugin-development/.claude-plugin/plugin.json exists
4. Uses plugins/plugin-development/ as target
5. Creates plugins/plugin-development/agents/code-reviewer.md

Result:

• Creates plugins/plugin-development/agents/code-reviewer.md
• Agent added to plugin-development plugin

Example 3: From Marketplace Root without --plugin

Context: Currently in /path/to/marketplace/ (marketplace root)

Input:

/plugin-development:add-agent code-reviewer "Reviews code for quality, security, and best practices"

Process:

1. Detects .claude-plugin/marketplace.json in current directory
2. No --plugin argument provided
3. Reads marketplace.json and discovers available plugins:
   • hello-world - A simple example plugin
   • plugin-development - Assist with Claude Code plugin development
4. Prompts user: "Which plugin should I add the agent to?"

   1. hello-world - A simple example plugin demonstrating basic Claude Code plugin functionality
   2. plugin-development - Assist with Claude Code plugin development: scaffold, validate, review, and team-ready distribution
   

5. User selects option 2
6. Uses plugins/plugin-development/ as target
7. Creates plugins/plugin-development/agents/code-reviewer.md

Result:

• Creates plugins/plugin-development/agents/code-reviewer.md
• Agent added to selected plugin

Agent Frontmatter

Required Fields

---
name: agent-name
description: Third-person description of what this agent does and when to invoke it
---

Field	Type	Description
name	String	Required. Unique identifier using lowercase letters and hyphens (e.g., code-reviewer, test-runner)
description	String	Required. Natural language description of when the agent should be invoked. Include "PROACTIVELY" for auto-delegation

Optional Fields

---
name: agent-name
description: Agent description. Use PROACTIVELY for auto-delegation.
tools: Read, Grep, Glob, Bash
model: sonnet
permissionMode: default
skills: skill1, skill2
---

Field	Type	Default	Description
tools	CSV String	Inherits all	Comma-separated list of tools (e.g., Read, Grep, Glob, Bash). If omitted, inherits all tools from main thread including MCP tools
model	String	sonnet	Which AI model to use. Valid values: sonnet, opus, haiku, inherit. Use inherit to match main conversation's model
permissionMode	String	default	How the agent handles permission requests. Valid values: default, acceptEdits, bypassPermissions, plan
skills	CSV String	None	Comma-separated list of skills to auto-load. Note: Agents do NOT inherit skills from parent conversation

Permission Modes Explained

Mode	Behavior
default	Standard permission handling - prompts for confirmation
acceptEdits	Automatically accept file edits without prompting
bypassPermissions	Skip permission requests entirely
plan	Plan mode - research and planning without execution

Model Options

Model	Description
sonnet	Claude Sonnet (default for subagents)
opus	Claude Opus
haiku	Claude Haiku (faster, lighter)
inherit	Use same model as main conversation

Deprecation Note

The capabilities field is NOT in official Anthropic docs and may be deprecated. Use tools for agents (not allowed-tools which is for skills).

For complete details on agents, see:

• Subagents documentation
• Plugin agents reference

Error Handling

Not in Plugin or Marketplace Directory

Error: "Not in a plugin or marketplace directory."

Solution: Navigate to either:

• A plugin directory (containing .claude-plugin/plugin.json), OR
• A marketplace root (containing .claude-plugin/marketplace.json)

Plugin Not Found

Error: "Plugin 'my-plugin' not found. Available plugins: hello-world, plugin-development"

Solution:

• Check plugin name spelling
• Use --plugin=<correct-name> with one of the available plugins
• Or navigate to the plugin directory directly

Invalid Agent Name

Error: "Agent name must be in kebab-case format (lowercase with hyphens)"

Solution: Use kebab-case format:

• ✅ Good: code-reviewer, security-auditor, api-generator
• ❌ Bad: CodeReviewer, code_reviewer, code reviewer

Missing Description

Error: "Description is required"

Solution: Provide description in quotes:

/plugin-development:add-agent code-reviewer "Reviews code for quality, security, and best practices"

When to Use Agents vs. Commands vs. Skills

Use an Agent when:

• Task requires deep, multi-file analysis
• Need separate context window (complex reasoning)
• Want detailed, structured report back
• Task has multiple steps that benefit from isolation

Use a Command when:

• Task is explicit, one-time action
• User needs to trigger on demand
• Task is straightforward with clear inputs/outputs

Use a Skill when:

• Want ambient, automatic activation
• Need persistent guidance throughout session
• Task benefits from progressive disclosure
• Should trigger based on context clues

Agent Design Best Practices

1. Focused Scope

✅ Good (focused):

# Code Security Auditor

Specializes in security analysis:
- SQL injection vulnerabilities
- XSS vulnerabilities
- Authentication issues

❌ Bad (too broad):

# General Code Helper

Does everything related to code.

2. Clear Tool Configuration

Configure appropriate tools for the agent's purpose:

# For read-only analysis agents:
tools: Read, Grep, Glob

# For agents that can modify files:
tools: Read, Edit, Write, Bash, Grep, Glob

# Omit to inherit all tools from main thread

3. Structured Output

Define consistent report format:

## Critical (P0)
- [List critical issues]

## High Priority (P1)
- [List high priority issues]

## Suggestions
- [List improvements]

4. Tool Restrictions

Agents typically don't modify files:

## Tool Access

- Read, Grep, Glob: For analysis
- No Write/Edit: Agent proposes, main conversation executes

Agent Workflow Template

All agents should follow a consistent structure:

1. **Understand Context**: Read relevant files
2. **Analyze**: Apply domain expertise
3. **Identify Issues**: Find problems/opportunities
4. **Prioritize**: Rank by severity/importance
5. **Recommend**: Provide actionable guidance
6. **Report**: Return structured findings

Common Agent Patterns

Auditor Pattern

For review/analysis agents:

• Reads multiple files
• Checks against standards/criteria
• Reports issues by severity
• Provides specific fix recommendations

Generator Pattern

For design/planning agents:

• Analyzes requirements
• Proposes architecture/approach
• Provides implementation steps
• Returns detailed plan

Refactoring Pattern

For code improvement agents:

• Analyzes existing code
• Identifies improvement opportunities
• Proposes refactoring steps
• Estimates impact/effort

Invocation Methods

Direct Invocation

User explicitly calls the agent:

/agents code-reviewer

Via Main Conversation

Claude uses Task tool:

Let me use the code-reviewer agent to analyze this...

From Skill

Skill escalates to agent for deep analysis:

For comprehensive review, delegate to the code-reviewer agent.

Best Practices

1. Single responsibility: One clear purpose
2. Structured output: Consistent report format
3. No side effects: Read-only, propose changes
4. Clear scope: 2-5 capabilities max
5. Fast feedback: Aim for < 30 seconds runtime
6. Actionable results: Specific, implementable recommendations

Common Mistakes to Avoid

❌ Too broad description

description: Does everything related to code

✅ Focused description with clear purpose

description: Security audit specialist. Scans for vulnerabilities, reviews authentication, and checks compliance. Use PROACTIVELY after code changes.

❌ Vague instructions

Analyze the code and find problems.

✅ Specific workflow

1. Read all .py files in src/
2. Check for SQL injection patterns
3. Verify authentication usage
4. Report findings by severity

Validation Checklist

After creating an agent:

□ Agent file created in agents/ directory
□ Frontmatter includes required 'name' field (lowercase with hyphens)
□ Frontmatter includes required 'description' field
□ Optional: 'tools' field configured (or inherits all)
□ Optional: 'model' field set (sonnet/opus/haiku/inherit)
□ Optional: 'permissionMode' configured if needed
□ Optional: 'skills' listed for auto-loading
□ Clear workflow defined in body
□ Output format specified
□ plugin.json has agents field (if using custom paths)
□ Purpose is focused and specific