agent-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Development for Claude Code Plugins

Claude Code 插件的 Agent 开发

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是可独立处理复杂多步骤任务的自主子进程。了解Agent的结构、触发条件和系统提示词设计，能够打造强大的自主能力。

核心概念：

Agent 用于自主工作，命令用于用户发起的操作
带有YAML前置元数据的Markdown文件格式
通过包含示例的描述字段触发
系统提示词定义Agent的行为
模型和颜色可自定义

Agent File Structure

Agent 文件结构

Complete Format

完整格式

markdown

---
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]

markdown

---
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)

name（必填）

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)

用于命名空间和调用的Agent标识符。

**格式：**仅小写字母、数字、连字符 **长度：**3-50个字符 **规则：**必须以字母或数字开头和结尾

优秀示例：

```
code-reviewer
```
```
test-generator
```
```
api-docs-writer
```
```
security-analyzer
```

错误示例：

```
helper
```
（过于通用）
```
-agent-
```
（以连字符开头/结尾）
```
my_agent
```
（使用下划线，不允许）
```
ag
```
（过短，少于3个字符）

description (required)

description（必填）

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

定义Claude应何时触发此Agent。这是最关键的字段。

必须包含：

触发条件（“Use this agent when...”）
多个
```
<example>
```
块展示使用场景
每个示例中包含上下文、用户请求和助手响应
```
<commentary>
```
解释触发此Agent的原因

格式：

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

最佳实践：

包含2-4个具体示例
展示主动和被动触发场景
覆盖同一意图的不同表述
在注释中解释推理逻辑
明确说明何时不应使用此Agent

model (required)

model（必填）

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.

Agent应使用的模型。

选项：

```
inherit
```
- 使用与父级相同的模型（推荐）
```
sonnet
```
- Claude Sonnet（平衡型）
```
opus
```
- Claude Opus（能力最强，成本较高）
```
haiku
```
- Claude Haiku（速度快，成本低）

**建议：**除非Agent需要特定模型能力，否则使用

inherit

color (required)

color（必填）

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

UI中Agent的视觉标识符。

选项：

blue

cyan

green

yellow

magenta

red

指导原则：

为同一插件中的不同Agent选择不同的颜色
为相似类型的Agent使用一致的颜色
蓝色/青色：分析、评审
绿色：面向成功的任务
黄色：提醒、验证
红色：关键任务、安全相关
品红色：创意、生成类任务

tools (optional)

tools（可选）

Restrict agent to specific tools.

Format: Array of tool names

yaml

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
```
["*"]
```

限制Agent仅能使用特定工具。

**格式：**工具名称数组

yaml

tools: ["Read", "Write", "Grep", "Bash"]

**默认值：**如果省略，Agent可访问所有工具

**最佳实践：**将工具限制为完成任务所需的最小集合（最小权限原则）

常见工具集：

只读分析：
```
["Read", "Grep", "Glob"]
```
代码生成：
```
["Read", "Write", "Grep"]
```
测试：
```
["Read", "Bash", "Grep"]
```
完全访问：省略此字段或使用
```
["*"]
```

System Prompt Design

系统提示词设计

The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.

Markdown正文将成为Agent的系统提示词。使用第二人称直接与Agent对话。

Structure

结构

Standard template:

markdown

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]

标准模板：

markdown

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

✅ 建议：

使用第二人称（“You are...”, “You will...”）
明确说明职责
提供分步流程
定义输出格式
包含质量标准
处理边缘情况
字符数保持在10,000以内

❌ 避免：

使用第一人称（“I am...”, “I will...”）
表述模糊或通用
省略流程步骤
未定义输出格式
跳过质量指导
忽略错误场景

Creating Agents

创建Agent

Method 1: AI-Assisted Generation

方法1：AI辅助生成

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.

使用此提示模板（提取自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..."
}

然后将结果转换为带有前置元数据的Agent文件格式。

完整模板请查看

examples/agent-creation-prompt.md

。

Method 2: Manual Creation

方法2：手动创建

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
```

选择Agent标识符（3-50个字符，小写，连字符分隔）
编写包含示例的描述
选择模型（通常为
```
inherit
```
）
选择用于视觉识别的颜色
定义工具（如果需要限制访问）
按照上述结构编写系统提示词
保存为
```
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

✅ 有效：code-reviewer, test-gen, api-analyzer-v2
❌ 无效：ag（过短）, -start（以连字符开头）, my_agent（使用下划线）

规则：

3-50个字符
仅允许小写字母、数字、连字符
必须以字母或数字开头和结尾
不允许下划线、空格或特殊字符

Description Validation

描述验证

Length: 10-5,000 characters Must include: Triggering conditions and examples Best: 200-1,000 characters with 2-4 examples

**长度：**10-5,000个字符 **必须包含：**触发条件和示例 **最佳：**200-1,000个字符，包含2-4个示例

System Prompt Validation

系统提示词验证

Length: 20-10,000 characters Best: 500-3,000 characters Structure: Clear responsibilities, process, output format

**长度：**20-10,000个字符 **最佳：**500-3,000个字符 **结构：**清晰的职责、流程、输出格式

Agent Organization

Agent 组织

Plugin Agents Directory

插件Agent目录

plugin-name/
└── agents/
    ├── analyzer.md
    ├── reviewer.md
    └── generator.md

All

.md

files in

agents/

are auto-discovered.

plugin-name/
└── agents/
    ├── analyzer.md
    ├── reviewer.md
    └── generator.md

agents/

目录下的所有

.md

文件都会被自动发现。

Namespacing

命名空间

Agents are namespaced automatically:

Single plugin:
```
agent-name
```
With subdirectories:
```
plugin:subdir:agent-name
```

Agent会自动添加命名空间：

单插件：
```
agent-name
```
带子目录：
```
plugin:subdir:agent-name
```

Testing Agents

测试Agent

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

创建测试场景以验证Agent是否正确触发：

编写带有特定触发示例的Agent
使用与示例相似的表述进行测试
检查Claude是否加载了该Agent
验证Agent提供了预期功能

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

确保系统提示词完整：

为Agent分配典型任务
检查它是否遵循流程步骤
验证输出格式是否正确
测试提示词中提到的边缘情况
确认符合质量标准

Quick Reference

快速参考

Minimal Agent

最简Agent

markdown

---
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]

markdown

---
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"]

字段	必填	格式	示例
name	是	小写连字符格式	code-reviewer
description	是	文本+示例	Use when... <example>...
model	是	inherit/sonnet/opus/haiku	inherit
color	是	颜色名称	blue
tools	否	工具名称数组	["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

建议：

✅ 在描述中包含2-4个具体示例
✅ 编写明确的触发条件
✅ 除非有特定需求，否则使用
```
inherit
```
作为模型
✅ 选择合适的工具（最小权限原则）
✅ 编写清晰、结构化的系统提示词
✅ 彻底测试Agent触发逻辑

避免：

❌ 使用无示例的通用描述
❌ 省略触发条件
❌ 为所有Agent使用相同颜色
❌ 授予不必要的工具访问权限
❌ 编写模糊的系统提示词
❌ 跳过测试

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

如需详细指导，请查阅：

references/system-prompt-design.md
- 完整的系统提示词模板
references/triggering-examples.md
- 示例格式和最佳实践

references/agent-creation-system-prompt.md
- 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

examples/

目录下的可用示例：

agent-creation-prompt.md
- AI辅助Agent生成模板
complete-agent-examples.md
- 适用于不同场景的完整Agent示例

Utility Scripts

实用脚本

Development tools in

scripts/

validate-agent.sh
- Validate agent file structure
test-agent-trigger.sh
- Test if agent triggers correctly

scripts/

目录下的开发工具：

validate-agent.sh
- 验证Agent文件结构
test-agent-trigger.sh
- 测试Agent是否正确触发

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.

为插件创建Agent的步骤：

定义Agent的用途和触发条件
选择创建方法（AI辅助或手动）
创建
```
agents/agent-name.md
```
文件
编写包含所有必填字段的前置元数据
按照最佳实践编写系统提示词
在描述中包含2-4个触发示例
使用
```
scripts/validate-agent.sh
```
进行验证
使用真实场景测试触发逻辑
在插件README中记录Agent信息

专注于明确的触发条件和全面的系统提示词，以实现自主操作。