---
id: sm-agent-development
name: "agent-development"
url: https://skills.yangsir.net/skill/sm-agent-development
author: anthropics
domain: ai-agent-core-development
tags: ["ai-agent-development", "llm-agents", "multi-agent-systems", "ai-orchestration", "prompt-engineering"]
install_count: 269
rating: 4.10 (20 reviews)
github: https://github.com/anthropics/claude-code
---

# agent-development

> 专注于AI智能体开发，特别是利用Claude Code等工具进行代码生成和工程实践，提升开发效率。

**Stats**: 269 installs · 4.1/5 (20 reviews)

## Before / After 对比

### AI智能体开发：从手动编码到智能代码生成与实践

## Readme

# 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.**

**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.
Weekly Installs0Repository[anthropics/claude-code](https://github.com/anthropics/claude-code)GitHub Stars79.3KFirst SeenJan 1, 1970Security Audits[Gen Agent Trust HubPass](/anthropics/claude-code/agent-development/security/agent-trust-hub)[SocketPass](/anthropics/claude-code/agent-development/security/socket)[SnykPass](/anthropics/claude-code/agent-development/security/snyk)

---
*Source: https://skills.yangsir.net/skill/sm-agent-development*
*Markdown mirror: https://skills.yangsir.net/api/skill/sm-agent-development/markdown*