agent-development

Agent Development for Claude Code Plugins

Overview

Agents are autonomous subprocesses that handle complex, multi-step tasks independently. Understanding agent structure, triggering conditions, and system prompt design enables creating powerful autonomous capabilities.

Key concepts:

• Agents are FOR autonomous work, commands are FOR user-initiated actions
• Markdown file format with YAML frontmatter
• Triggering via description field with examples
• System prompt defines agent behavior
• Model and color customization

Agent File Structure

Complete Format

---
name: agent-identifier
description: Use this agent when [triggering conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See "When to invoke" in the agent body for worked scenarios.
model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---

You are [agent role description]...

## When to invoke

[Two to four representative scenarios written as prose, e.g.:]
- **[Scenario name].** [What the situation looks like and what the agent should do.]
- **[Scenario name].** [Same.]

**Your Core Responsibilities:**
1. [Responsibility 1]
2. [Responsibility 2]

**Analysis Process:**
[Step-by-step workflow]

**Output Format:**
[What to return]

Frontmatter Fields

name (required)

Agent identifier used for namespacing and invocation.

Format: lowercase, numbers, hyphens only Length: 3-50 characters Pattern: Must start and end with alphanumeric

Good examples:

• code-reviewer
• test-generator
• api-docs-writer
• security-analyzer

Bad examples:

• helper (too generic)
• -agent- (starts/ends with hyphen)
• my_agent (underscores not allowed)
• ag (too short, < 3 chars)

description (required)

Defines when Claude should trigger this agent. This is the most critical field — it is loaded into context whenever the agent is registered, so the harness can decide when to dispatch.

Must include:

• Triggering conditions ("Use this agent when...")
• A short prose summary of the typical trigger scenarios
• A pointer to a "When to invoke" section in the agent body for the detailed worked scenarios

Format:

Use this agent when [conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See "When to invoke" in the agent body for worked scenarios.

Best practices:

• Name 2-4 trigger scenarios in the prose summary
• Cover both proactive (assistant invokes itself) and reactive (user requests) triggering
• Cover different phrasings of the same intent
• Be specific about when NOT to use the agent
• Put detailed scenarios in the body under "When to invoke" as a bullet list of prose descriptions

model (required)

Which model the agent should use.

Options:

• inherit - Use same model as parent (recommended)
• sonnet - Claude Sonnet (balanced)
• opus - Claude Opus (most capable, expensive)
• haiku - Claude Haiku (fast, cheap)

Recommendation: Use inherit unless agent needs specific model capabilities.

color (required)

Visual identifier for agent in UI.

Options: blue, cyan, green, yellow, magenta, red

Guidelines:

• Choose distinct colors for different agents in same plugin
• Use consistent colors for similar agent types
• Blue/cyan: Analysis, review
• Green: Success-oriented tasks
• Yellow: Caution, validation
• Red: Critical, security
• Magenta: Creative, generation

tools (optional)

Restrict agent to specific tools.

Format: Array of tool names

tools: ["Read", "Write", "Grep", "Bash"]

Default: If omitted, agent has access to all tools

Best practice: Limit tools to minimum needed (principle of least privilege)

Common tool sets:

• Read-only analysis: ["Read", "Grep", "Glob"]
• Code generation: ["Read", "Write", "Grep"]
• Testing: ["Read", "Bash", "Grep"]
• Full access: Omit field or use ["*"]

System Prompt Design

The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.

Structure

Standard template:

You are [role] specializing in [domain].

**Your Core Responsibilities:**
1. [Primary responsibility]
2. [Secondary responsibility]
3. [Additional responsibilities...]

**Analysis Process:**
1. [Step one]
2. [Step two]
3. [Step three]
[...]

**Quality Standards:**
- [Standard 1]
- [Standard 2]

**Output Format:**
Provide results in this format:
- [What to include]
- [How to structure]

**Edge Cases:**
Handle these situations:
- [Edge case 1]: [How to handle]
- [Edge case 2]: [How to handle]

Best Practices

✅ DO:

• Write in second person ("You are...", "You will...")
• Be specific about responsibilities
• Provide step-by-step process
• Define output format
• Include quality standards
• Address edge cases
• Keep under 10,000 characters

❌ DON'T:

• Write in first person ("I am...", "I will...")
• Be vague or generic
• Omit process steps
• Leave output format undefined
• Skip quality guidance
• Ignore error cases

Creating Agents

Method 1: AI-Assisted Generation

Use this prompt pattern (extracted from Claude Code):

Create an agent configuration based on this request: "[YOUR DESCRIPTION]"

Requirements:
1. Extract core intent and responsibilities
2. Design expert persona for the domain
3. Create comprehensive system prompt with:
   - Clear behavioral boundaries
   - Specific methodologies
   - Edge case handling
   - Output format
   - A "When to invoke" section listing 2-4 trigger scenarios as prose bullets
4. Create identifier (lowercase, hyphens, 3-50 chars)
5. Write description with triggering conditions and a short prose summary of trigger scenarios

Return JSON with:
{
  "identifier": "agent-name",
  "whenToUse": "Use this agent when... Typical triggers include [...]. See \"When to invoke\" in the agent body.",
  "systemPrompt": "You are..."
}

Then convert to agent file format with frontmatter.

See examples/agent-creation-prompt.md for complete template.

Method 2: Manual Creation

• Choose agent identifier (3-50 chars, lowercase, hyphens)
• Write description with examples
• Select model (usually inherit)
• Choose color for visual identification
• Define tools (if restricting access)
• Write system prompt with structure above
• Save as agents/agent-name.md

Validation Rules

Identifier Validation

✅ Valid: code-reviewer, test-gen, api-analyzer-v2
❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)

Rules:

• 3-50 characters
• Lowercase letters, numbers, hyphens only
• Must start and end with alphanumeric
• No underscores, spaces, or special characters

Description Validation

Length: 10-5,000 characters Must include: Triggering conditions and examples Best: 200-1,000 characters with 2-4 examples

System Prompt Validation

Length: 20-10,000 characters Best: 500-3,000 characters Structure: Clear responsibilities, process, output format

Agent Organization

Plugin Agents Directory

plugin-name/
└── agents/
    ├── analyzer.md
    ├── reviewer.md
    └── generator.md

All .md files in agents/ are auto-discovered.

Namespacing

Agents are namespaced automatically:

• Single plugin: agent-name
• With subdirectories: plugin:subdir:agent-name

Testing Agents

Test Triggering

Create test scenarios to verify agent triggers correctly:

• Write agent with specific triggering examples
• Use similar phrasing to examples in test
• Check Claude loads the agent
• Verify agent provides expected functionality

Test System Prompt

Ensure system prompt is complete:

• Give agent typical task
• Check it follows process steps
• Verify output format is correct
• Test edge cases mentioned in prompt
• Confirm quality standards are met

Quick Reference

Minimal Agent

---
name: simple-agent
description: Use this agent when [condition]. Typical triggers include [trigger 1] and [trigger 2]. See "When to invoke" in the agent body.
model: inherit
color: blue
---

You are an agent that [does X].

## When to invoke

- **[Scenario A].** [Description.]
- **[Scenario B].** [Description.]

Process:
1. [Step 1]
2. [Step 2]

Output: [What to provide]

Frontmatter Fields Summary

| Field | Required | Format | Example | |-------|----------|--------|---------| | name | Yes | lowercase-hyphens | code-reviewer | | description | Yes | Prose triggers | Use when... Typical triggers include... | | model | Yes | inherit/sonnet/opus/haiku | inherit | | color | Yes | Color name | blue | | tools | No | Array of tool names | ["Read", "Grep"] |

Best Practices

DO:

• ✅ Name 2-4 trigger scenarios in the description (as prose)
• ✅ Put detailed worked scenarios in a "When to invoke" body section, as prose bullets
• ✅ Write specific triggering conditions
• ✅ Use inherit for model unless specific need
• ✅ Choose appropriate tools (least privilege)
• ✅ Write clear, structured system prompts
• ✅ Test agent triggering thoroughly

DON'T:

• ❌ Use generic descriptions without trigger scenarios
• ❌ Omit triggering conditions
• ❌ Give all agents same color
• ❌ Grant unnecessary tool access
• ❌ Write vague system prompts
• ❌ Skip testing

Additional Resources

Reference Files

For detailed guidance, consult:

• references/system-prompt-design.md - Complete system prompt patterns
• references/triggering-examples.md - Example formats and best practices
• references/agent-creation-system-prompt.md - The exact prompt from Claude Code

Example Files

Working examples in examples/:

• agent-creation-prompt.md - AI-assisted agent generation template
• complete-agent-examples.md - Full agent examples for different use cases

Utility Scripts

Development tools in scripts/:

• validate-agent.sh - Validate agent file structure
• test-agent-trigger.sh - Test if agent triggers correctly

Implementation Workflow

To create an agent for a plugin:

• Define agent purpose and triggering conditions
• Choose creation method (AI-assisted or manual)
• Create agents/agent-name.md file
• Write frontmatter with all required fields
• Write system prompt following best practices
• Name 2-4 trigger scenarios in description (prose) and detail them in a "When to invoke" body section
• Validate with scripts/validate-agent.sh
• Test triggering with real scenarios
• Document agent in plugin README

Focus on clear triggering conditions and comprehensive system prompts for autonomous operation.