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]. Examples:

<example> Context: [Situation description] user: "[User request]" assistant: "[How assistant should respond and use this agent]" <commentary> [Why this agent should be triggered] </commentary> </example>

<example> [Additional example...] </example>

model: inherit color: blue tools: ["Read", "Write", "Grep"]

You are [agent role description]...

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.

Must include:

• Triggering conditions ("Use this agent when...")

• Multiple <example> blocks showing usage

• Context, user request, and assistant response in each example

• <commentary> explaining why agent triggers

Format:

Use this agent when [conditions]. Examples:

<example> Context: [Scenario description] user: "[What user says]" assistant: "[How Claude should respond]" <commentary> [Why this agent is appropriate] </commentary> </example>

[More examples...]

Best practices:

• Include 2-4 concrete examples

• Show proactive and reactive triggering

• Cover different phrasings of same intent

• Explain reasoning in commentary

• Be specific about when NOT to use the agent

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
4. Create identifier (lowercase, hyphens, 3-50 chars)
5. Write description with triggering conditions
6. Include 2-3 <example> blocks showing when to use

Return JSON with: { "identifier": "agent-name", "whenToUse": "Use this agent when... Examples: <example>...</example>", "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... Examples: <example>...</example> model: inherit color: blue

You are an agent that [does X].

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 Text + examples Use when... ...

model Yes inherit/sonnet/opus/haiku inherit

color Yes Color name blue

tools No Array of tool names ["Read", "Grep"]

Best Practices

DO:

• ✅ Include 2-4 concrete examples in description

• ✅ 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 examples

• ❌ 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

• Include 2-4 triggering examples in description

• 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.