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.