agent-identifier

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 frontmatter的Markdown文件格式
通过包含示例的description字段触发
系统提示词定义Agent行为
可自定义模型和颜色

When to Use

适用场景

Use this skill when the user asks to:

Create an agent
Add an agent
Write a subagent
Define agent frontmatter
Decide when to use description examples
Configure agent tools, colors, or model behavior
Design autonomous agent structure, triggering conditions, or system prompts

当用户提出以下需求时，可使用本技能：

创建Agent
添加Agent
编写子Agent
定义Agent的frontmatter
确定何时使用描述示例
配置Agent的工具、颜色或模型行为
设计自主Agent的结构、触发条件或系统提示词

When Not to Use

不适用场景

Do not use this skill for:

Slash command design
Hook configuration
MCP server setup
General plugin layout questions that belong to
```
plugin-structure
```

本技能不适用于：

斜杠命令设计
Hook配置
MCP服务器设置
属于
```
plugin-structure
```
的通用插件布局问题

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: 当[触发条件]时使用本Agent。示例：

<example>
Context: [场景描述]
user: "[用户请求]"
assistant: "[助手应如何响应并使用本Agent]"
<commentary>
[为何应触发本Agent]
</commentary>
</example>

<example>
[更多示例...]
</example>

model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---

你是[Agent角色描述]...

**核心职责：**
1. [职责1]
2. [职责2]

**分析流程：**
[分步工作流]

**输出格式：**
[返回内容要求]

Frontmatter Fields

Frontmatter字段

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。这是最关键的字段。

必须包含：

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

格式：

当[条件]时使用本Agent。示例：

<example>
Context: [场景描述]
user: "[用户表述]"
assistant: "[Claude应如何响应]"
<commentary>
[为何本Agent适用]
</commentary>
</example>

[更多示例...]

最佳实践：

包含2-4个具体示例
展示主动和被动触发场景
覆盖同一意图的不同表述方式
在commentary中解释推理过程
明确说明何时不应使用本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

你是专注于[领域]的[角色]。

**核心职责：**
1. [主要职责]
2. [次要职责]
3. [其他职责...]

**分析流程：**
1. [步骤一]
2. [步骤二]
3. [步骤三]
[...]

**质量标准：**
- [标准1]
- [标准2]

**输出格式：**
请按以下格式提供结果：
- [包含内容]
- [结构要求]

**边缘情况：**
处理以下场景：
- [边缘情况1]：[处理方式]
- [边缘情况2]：[处理方式]

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

✅ 建议：

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

❌ 避免：

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

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）：

根据以下请求创建Agent配置："[你的描述]"

要求：
1. 提取核心意图和职责
2. 为该领域设计专家角色
3. 创建完整的系统提示词，包含：
   - 明确的行为边界
   - 具体方法
   - 边缘情况处理
   - 输出格式
4. 创建标识符（小写、连字符、3-50个字符）
5. 编写包含触发条件的描述
6. 包含2-3个`<example>`块展示使用场景

返回JSON格式：
{
  "identifier": "agent-name",
  "whenToUse": "当...时使用本Agent。示例：<example>...</example>",
  "systemPrompt": "你是..."
}

然后转换为带有frontmatter的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: 当...时使用本Agent。示例：<example>...</example>
model: inherit
color: blue
---

你是一个[执行X任务]的Agent。

流程：
1. [步骤1]
2. [步骤2]

输出：[提供内容要求]

Frontmatter Fields Summary

Frontmatter字段汇总

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	是	文本+示例	当...时使用 <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
```
文件
编写包含所有必填字段的frontmatter
按照最佳实践编写系统提示词
在描述中包含2-4个触发示例
使用
```
scripts/validate-agent.sh
```
验证
使用真实场景测试触发逻辑
在插件README中记录Agent信息

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