AutoGineer
Generated banner for Agent Development
Generated logo for Agent Development

Agent Development

AnthropicOfficialPublished by Anthropic

  • Skill
  • Guidelines
  • Agent tooling
  • Apache-2.0
  • Low risk
  • Has scripts
Download ZIP

From the author

This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
— the description by Anthropic

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides the framework and best practices for developing autonomous agents within Claude Code. It covers the complete agent lifecycle, including file structure, YAML frontmatter configuration, system prompt design, and testing procedures. It emphasizes creating agents that are modular, well-defined, and capable of handling multi-step tasks independently through clear triggering conditions and robust behavioral instructions.

What it does

  • Defines the required markdown and YAML frontmatter structure for agent files.
  • Provides patterns for writing effective system prompts in the second person.
  • Outlines best practices for defining triggering conditions and scenarios.
  • Offers guidance on model selection, color-coding for UI, and tool access control.
  • Includes templates and prompts for AI-assisted agent generation.
  • Provides validation and testing workflows to ensure agent reliability.

When to use it

  • When you need to create a new autonomous agent for a Claude Code plugin.
  • When you are refining an existing agent's system prompt or triggering logic.
  • When you need to ensure your agent configuration follows established structural standards.
  • When you are troubleshooting why an agent is not triggering as expected.

Advantages

  • Standardizes agent development across different plugins.
  • Improves agent reliability through clear triggering scenarios.
  • Promotes the principle of least privilege via tool restriction.
  • Facilitates consistent behavior through structured system prompt templates.

Usage examples

“Create an agent configuration for a security-analyzer that checks code for vulnerabilities.”
The agent will generate a JSON object with a unique identifier, a description with prose triggers, and a system prompt structured with responsibilities, analysis processes, and quality standards.
“How should I structure the system prompt for a new documentation-writer agent?”
The agent will provide a template including core responsibilities, a generation process, quality standards, output format, and edge case handling.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/anthropics/agent-development/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip agent-development.zip -d .agents/skills

Documentation by Anthropic

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:

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

  2. A short prose summary of the typical trigger scenarios

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

  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 [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
FieldRequiredFormatExample
nameYeslowercase-hyphenscode-reviewer
descriptionYesProse triggersUse when... Typical triggers include...
modelYesinherit/sonnet/opus/haikuinherit
colorYesColor nameblue
toolsNoArray 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:

  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. Name 2-4 trigger scenarios in description (prose) and detail them in a "When to invoke" body section

  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.

Files

references/system-prompt-design.md

System Prompt Design Patterns

Complete guide to writing effective agent system prompts that enable autonomous, high-quality operation.

Core Structure

Every agent system prompt should follow this proven structure:

You are [specific role] specializing in [specific domain].

**Your Core Responsibilities:**
1. [Primary responsibility - the main task]
2. [Secondary responsibility - supporting task]
3. [Additional responsibilities as needed]

**[Task Name] Process:**
1. [First concrete step]
2. [Second concrete step]
3. [Continue with clear steps]
[...]

**Quality Standards:**
- [Standard 1 with specifics]
- [Standard 2 with specifics]
- [Standard 3 with specifics]

**Output Format:**
Provide results structured as:
- [Component 1]
- [Component 2]
- [Include specific formatting requirements]

**Edge Cases:**
Handle these situations:
- [Edge case 1]: [Specific handling approach]
- [Edge case 2]: [Specific handling approach]

Pattern 1: Analysis Agents

For agents that analyze code, PRs, or documentation:

You are an expert [domain] analyzer specializing in [specific analysis type].

**Your Core Responsibilities:**
1. Thoroughly analyze [what] for [specific issues]
2. Identify [patterns/problems/opportunities]
3. Provide actionable recommendations

**Analysis Process:**
1. **Gather Context**: Read [what] using available tools
2. **Initial Scan**: Identify obvious [issues/patterns]
3. **Deep Analysis**: Examine [specific aspects]:
   - [Aspect 1]: Check for [criteria]
   - [Aspect 2]: Verify [criteria]
   - [Aspect 3]: Assess [criteria]
4. **Synthesize Findings**: Group related issues
5. **Prioritize**: Rank by [severity/impact/urgency]
6. **Generate Report**: Format according to output template

**Quality Standards:**
- Every finding includes file:line reference
- Issues categorized by severity (critical/major/minor)
- Recommendations are specific and actionable
- Positive observations included for balance

**Output Format:**
## Summary
[2-3 sentence overview]

## Critical Issues
- [file:line] - [Issue description] - [Recommendation]

## Major Issues
[...]

## Minor Issues
[...]

## Recommendations
[...]

**Edge Cases:**
- No issues found: Provide positive feedback and validation
- Too many issues: Group and prioritize top 10
- Unclear code: Request clarification rather than guessing

Pattern 2: Generation Agents

For agents that create code, tests, or documentation:

You are an expert [domain] engineer specializing in creating high-quality [output type].

**Your Core Responsibilities:**
1. Generate [what] that meets [quality standards]
2. Follow [specific conventions/patterns]
3. Ensure [correctness/completeness/clarity]

**Generation Process:**
1. **Understand Requirements**: Analyze what needs to be created
2. **Gather Context**: Read existing [code/docs/tests] for patterns
3. **Design Structure**: Plan [architecture/organization/flow]
4. **Generate Content**: Create [output] following:
   - [Convention 1]
   - [Convention 2]
   - [Best practice 1]
5. **Validate**: Verify [correctness/completeness]
6. **Document**: Add comments/explanations as needed

**Quality Standards:**
- Follows project conventions (check CLAUDE.md)
- [Specific quality metric 1]
- [Specific quality metric 2]
- Includes error handling
- Well-documented and clear

**Output Format:**
Create [what] with:
- [Structure requirement 1]
- [Structure requirement 2]
- Clear, descriptive naming
- Comprehensive coverage

**Edge Cases:**
- Insufficient context: Ask user for clarification
- Conflicting patterns: Follow most recent/explicit pattern
- Complex requirements: Break into smaller pieces

Pattern 3: Validation Agents

For agents that validate, check, or verify:

You are an expert [domain] validator specializing in ensuring [quality aspect].

**Your Core Responsibilities:**
1. Validate [what] against [criteria]
2. Identify violations and issues
3. Provide clear pass/fail determination

**Validation Process:**
1. **Load Criteria**: Understand validation requirements
2. **Scan Target**: Read [what] needs validation
3. **Check Rules**: For each rule:
   - [Rule 1]: [Validation method]
   - [Rule 2]: [Validation method]
4. **Collect Violations**: Document each failure with details
5. **Assess Severity**: Categorize issues
6. **Determine Result**: Pass only if [criteria met]

**Quality Standards:**
- All violations include specific locations
- Severity clearly indicated
- Fix suggestions provided
- No false positives

**Output Format:**
## Validation Result: [PASS/FAIL]

## Summary
[Overall assessment]

## Violations Found: [count]
### Critical ([count])
- [Location]: [Issue] - [Fix]

### Warnings ([count])
- [Location]: [Issue] - [Fix]

## Recommendations
[How to fix violations]

**Edge Cases:**
- No violations: Confirm validation passed
- Too many violations: Group by type, show top 20
- Ambiguous rules: Document uncertainty, request clarification

Pattern 4: Orchestration Agents

For agents that coordinate multiple tools or steps:

You are an expert [domain] orchestrator specializing in coordinating [complex workflow].

**Your Core Responsibilities:**
1. Coordinate [multi-step process]
2. Manage [resources/tools/dependencies]
3. Ensure [successful completion/integration]

**Orchestration Process:**
1. **Plan**: Understand full workflow and dependencies
2. **Prepare**: Set up prerequisites
3. **Execute Phases**:
   - Phase 1: [What] using [tools]
   - Phase 2: [What] using [tools]
   - Phase 3: [What] using [tools]
4. **Monitor**: Track progress and handle failures
5. **Verify**: Confirm successful completion
6. **Report**: Provide comprehensive summary

**Quality Standards:**
- Each phase completes successfully
- Errors handled gracefully
- Progress reported to user
- Final state verified

**Output Format:**
## Workflow Execution Report

### Completed Phases
- [Phase]: [Result]

### Results
- [Output 1]
- [Output 2]

### Next Steps
[If applicable]

**Edge Cases:**
- Phase failure: Attempt retry, then report and stop
- Missing dependencies: Request from user
- Timeout: Report partial completion

Writing Style Guidelines

Tone and Voice

Use second person (addressing the agent):

✅ You are responsible for...
✅ You will analyze...
✅ Your process should...

❌ The agent is responsible for...
❌ This agent will analyze...
❌ I will analyze...
Clarity and Specificity

Be specific, not vague:

✅ Check for SQL injection by examining all database queries for parameterization
❌ Look for security issues

✅ Provide file:line references for each finding
❌ Show where issues are

✅ Categorize as critical (security), major (bugs), or minor (style)
❌ Rate the severity of issues
Actionable Instructions

Give concrete steps:

✅ Read the file using the Read tool, then search for patterns using Grep
❌ Analyze the code

✅ Generate test file at test/path/to/file.test.ts
❌ Create tests

Common Pitfalls

❌ Vague Responsibilities
**Your Core Responsibilities:**
1. Help the user with their code
2. Provide assistance
3. Be helpful

Why bad: Not specific enough to guide behavior.

✅ Specific Responsibilities
**Your Core Responsibilities:**
1. Analyze TypeScript code for type safety issues
2. Identify missing type annotations and improper 'any' usage
3. Recommend specific type improvements with examples
❌ Missing Process Steps
Analyze the code and provide feedback.

Why bad: Agent doesn't know HOW to analyze.

✅ Clear Process
**Analysis Process:**
1. Read code files using Read tool
2. Scan for type annotations on all functions
3. Check for 'any' type usage
4. Verify generic type parameters
5. List findings with file:line references
❌ Undefined Output
Provide a report.

Why bad: Agent doesn't know what format to use.

✅ Defined Output Format
**Output Format:**
## Type Safety Report

### Summary
[Overview of findings]

### Issues Found
- `file.ts:42` - Missing return type on `processData`
- `utils.ts:15` - Unsafe 'any' usage in parameter

### Recommendations
[Specific fixes with examples]

Length Guidelines

Minimum Viable Agent

~500 words minimum:

  • Role description

  • 3 core responsibilities

  • 5-step process

  • Output format

Standard Agent

~1,000-2,000 words:

  • Detailed role and expertise

  • 5-8 responsibilities

  • 8-12 process steps

  • Quality standards

  • Output format

  • 3-5 edge cases

Comprehensive Agent

~2,000-5,000 words:

  • Complete role with background

  • Comprehensive responsibilities

  • Detailed multi-phase process

  • Extensive quality standards

  • Multiple output formats

  • Many edge cases

  • Examples within system prompt

Avoid > 10,000 words: Too long, diminishing returns.

Testing System Prompts

Test Completeness

Can the agent handle these based on system prompt alone?

  • [ ] Typical task execution

  • [ ] Edge cases mentioned

  • [ ] Error scenarios

  • [ ] Unclear requirements

  • [ ] Large/complex inputs

  • [ ] Empty/missing inputs

Test Clarity

Read the system prompt and ask:

  • Can another developer understand what this agent does?

  • Are process steps clear and actionable?

  • Is output format unambiguous?

  • Are quality standards measurable?

Iterate Based on Results

After testing agent:

  1. Identify where it struggled

  2. Add missing guidance to system prompt

  3. Clarify ambiguous instructions

  4. Add process steps for edge cases

  5. Re-test

Conclusion

Effective system prompts are:

  • Specific: Clear about what and how

  • Structured: Organized with clear sections

  • Complete: Covers normal and edge cases

  • Actionable: Provides concrete steps

  • Testable: Defines measurable standards

Use the patterns above as templates, customize for your domain, and iterate based on agent performance.

Requirements and compatibility

Written for: Claude Code, Claude apps

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

What our scanner noticed· Low risk

  • Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Anthropic
Publisher
Anthropic (Official)
Source
anthropics/claude-plugins-official · plugins/plugin-dev/skills/agent-development · commit 0412be7
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from plugins/plugin-dev/LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Anthropic or Anthropic.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download agent-development.zip