harsh040506/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]. 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 because it is the only mechanism by which Claude decides to spawn rather than respond directly. Claude compares the current conversation context against all agent descriptions simultaneously; the agent whose description best matches the situation wins.

This means the description field is not documentation — it is a selector. It needs to be precise enough to distinguish this agent from adjacent agents and general-purpose responses, and broad enough to match different phrasings of the same intent.

Must include:

1. Triggering conditions ("Use this agent when...")
2. Multiple <example> blocks showing usage
3. Context, user request, and assistant response in each example
4. <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...]

Why the <example> format works mechanistically:

Examples are more powerful than trigger keywords because they demonstrate conversational context, not just surface vocabulary. The commentary block matters disproportionately — it teaches Claude the reasoning behind the trigger, which generalizes to phrasings and contexts the examples don't explicitly cover.

A weak commentary just restates the obvious: "This agent handles code review." A strong commentary explains the discrimination: "The user completed a feature and wants validation before committing — use this agent rather than responding inline, because the agent has the full review rubric from CLAUDE.md in its system prompt and applies it systematically, whereas an inline response would assess quality subjectively."

Best practices:

• Include 2-4 concrete examples
• Vary the triggering surface: show proactive triggers (after an action), reactive triggers (explicit request), and indirect triggers (user doesn't name the agent but clearly needs it)
• Cover different phrasings of the same intent — formal, casual, abbreviated
• Make commentary explain the why of the choice, not just the what
• Include at least one example showing when NOT to use the agent if there are adjacent agents that might compete

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.

Why second person matters: The system prompt establishes the agent's identity and behavioral frame before any task arrives. Writing in second person ("You are...", "You will...") activates the model's capacity to adopt a consistent persona and apply that persona's judgment across varying inputs. First-person or third-person framing diffuses this — the model treats it as information about an external entity rather than a self-definition to embody.

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...") — establishes identity, not just instructions
• Be specific about responsibilities — vague responsibilities produce vague output; specificity sets a measurable bar
• Provide step-by-step process — explicit sequencing prevents the model from skipping steps that seem optional but aren't
• Define output format — without a format spec, the model improvises structure, leading to inconsistent and hard-to-parse outputs across runs
• Include quality standards — give the agent a standard to grade itself against, not just a task to attempt
• Address edge cases — edge case handling is the difference between an agent that works on demonstrations vs. one that works in production
• Keep under 10,000 characters — beyond this, early instructions get deprioritized in the context window

❌ DON'T:

• Write in first person ("I am...", "I will...") — weakens the behavioral frame and confuses the agent's self-model
• Be vague or generic — "Do a good job" is not a standard; "Report only issues with confidence ≥ 80" is
• Omit process steps — the agent will fill in gaps with its own defaults, which may not match the plugin's intent
• Leave output format undefined — causes hallucinated structure that downstream systems or users must re-parse
• Skip quality guidance — without it the agent optimizes for completion, not correctness
• Ignore error cases — unhandled errors produce silent failures or unhelpful generic messages

Depth Checklist for System Prompts

Before finalizing a system prompt, verify each structural section meets its depth standard:

| Section | Shallow version | Adequate version | |---------|----------------|------------------| | Role definition | "You are a code reviewer." | "You are an expert code reviewer specializing in TypeScript and React, with emphasis on catching type safety violations and accessibility regressions." | | Process steps | "1. Review the code. 2. Report issues." | "1. Read the full diff before forming opinions — early lines often get clarified by later context. 2. Score each issue 0–100; only surface those ≥ 80. 3. Group by severity..." | | Output format | "Provide a summary." | "Start with a one-line verdict (Pass / Needs Work). Then list issues grouped into Critical (90–100) and Important (80–89), each with: file path, line number, rule violated, fix suggestion." | | Edge cases | (absent) | "If no high-confidence issues exist, confirm the code meets standards with a brief summary. Do not invent issues to fill the report." |

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

1. Choose agent identifier (3-50 chars, lowercase, hyphens)
2. Write description with examples
3. Select model (usually inherit)
4. Choose color for visual identification
5. Define tools (if restricting access)
6. Write system prompt with structure above
7. 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:

1. Write agent with specific triggering examples
2. Use similar phrasing to examples in test
3. Check Claude loads the agent
4. Verify agent provides expected functionality

Test System Prompt

Ensure system prompt is complete:

1. Give agent typical task
2. Check it follows process steps
3. Verify output format is correct
4. Test edge cases mentioned in prompt
5. 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... <example>... | | 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:

1. Define agent purpose and triggering conditions
2. Choose creation method (AI-assisted or manual)
3. Create agents/agent-name.md file
4. Write frontmatter with all required fields
5. Write system prompt following best practices
6. Include 2-4 triggering examples in description
7. Validate with scripts/validate-agent.sh
8. Test triggering with real scenarios
9. Document agent in plugin README

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