name: 代理开发 description: 当用户询问“创建代理”、“添加代理”、“编写子代理”、“代理frontmatter”、“何时使用描述”、“代理示例”、“代理工具”、“代理颜色”、“自主代理”，或需要关于代理结构、系统提示、触发条件或Claude Code插件代理开发最佳实践的指导时，应使用此技能。

Claude Code插件的代理开发

概述

代理是自主子进程，独立处理复杂的多步骤任务。理解代理结构、触发条件和系统提示设计能够创建强大的自主能力。

关键概念：

代理用于自主工作，命令用于用户发起的操作
带有YAML frontmatter的Markdown文件格式
通过带有示例的描述字段触发
系统提示定义代理行为
模型和颜色自定义

代理文件结构

完整格式

---
name: 代理标识符
description: 当[触发条件]时使用此代理。示例：

<example>
Context: [情境描述]
user: "[用户请求]"
assistant: "[助手应如何响应并使用此代理]"
<commentary>
[为何应触发此代理]
</commentary>
</example>

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

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

您是[代理角色描述]...

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

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

**输出格式：**
[提供内容]

Frontmatter字段

name（必需）

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

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

良好示例：

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

不良示例：

helper（太泛化）
-agent-（以连字符开头/结尾）
my_agent（不允许下划线）
ag（太短，< 3字符）

description（必需）

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

必须包括：

触发条件（“当…时使用此代理”）
多个<example>块显示用法
每个示例中的Context、用户请求和助手响应
<commentary>解释为何触发代理

格式：

当[条件]时使用此代理。示例：

<example>
Context: [场景描述]
user: "[用户所说]"
assistant: "[Claude应如何响应]"
<commentary>
[为何此代理合适]
</commentary>
</example>

[更多示例...]

最佳实践：

包括2-4个具体示例
显示主动和被动触发
覆盖相同意图的不同表述
在评论中解释推理
具体说明何时不应使用代理

model（必需）

代理应使用的模型。

选项：

inherit - 使用与父模型相同的模型（推荐）
sonnet - Claude Sonnet（平衡）
opus - Claude Opus（最强大，昂贵）
haiku - Claude Haiku（快速，便宜）

推荐： 除非代理需要特定模型能力，否则使用inherit。

color（必需）

UI中代理的视觉标识符。

选项： blue, cyan, green, yellow, magenta, red

指南：

为同一插件中不同代理选择不同颜色
为类似代理类型使用一致颜色
蓝色/青色：分析、审查
绿色：成功导向任务
黄色：谨慎、验证
红色：关键、安全
洋红色：创意、生成

tools（可选）

将代理限制为特定工具。

格式： 工具名称数组

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

默认： 如果省略，代理可访问所有工具

最佳实践： 将工具限制在最小所需（最小权限原则）

常见工具集：

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

系统提示设计

Markdown正文成为代理的系统提示。以第二人称书写，直接向代理陈述。

结构

标准模板：

您是[角色]，专长于[领域]。

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

**分析过程：**
1. [第一步]
2. [第二步]
3. [第三步]
[...]

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

**输出格式：**
按此格式提供结果：
- [包含内容]
- [如何结构]

**边缘案例：**
处理这些情况：
- [边缘案例1]：[如何处理]
- [边缘案例2]：[如何处理]

最佳实践

✅ 应做：

以第二人称书写（“您是…”、“您将…”）
明确职责
提供逐步过程
定义输出格式
包括质量标准
处理边缘案例
保持少于10,000字符

❌ 不应做：

以第一人称书写（“我是…”、“我将…”）
模糊或泛化
省略过程步骤
未定义输出格式
跳过质量指导
忽略错误案例

创建代理

方法1：AI辅助生成

使用此提示模式（从Claude Code提取）：

基于此请求创建代理配置：“[您的描述]”

要求：
1. 提取核心意图和职责
2. 为领域设计专家角色
3. 创建全面系统提示，包括：
   - 明确行为边界
   - 具体方法
   - 边缘案例处理
   - 输出格式
4. 创建标识符（小写、连字符、3-50字符）
5. 编写带触发条件的描述
6. 包括2-3个<example>块显示何时使用

返回JSON：
{
  "identifier": "代理名称",
  "whenToUse": "当...时使用此代理。示例：<example>...</example>",
  "systemPrompt": "您是...”
}

然后转换为代理文件格式并添加frontmatter。

查看examples/agent-creation-prompt.md获取完整模板。

方法2：手动创建

选择代理标识符（3-50字符、小写、连字符）
编写带示例的描述
选择模型（通常inherit）
选择颜色用于视觉标识
定义工具（如果限制访问）
编写系统提示，遵循上述结构
保存为agents/代理名称.md

验证规则

标识符验证

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

规则：

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

描述验证

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

系统提示验证

长度： 20-10,000字符 最佳： 500-3,000字符 结构： 明确职责、过程、输出格式

代理组织

插件代理目录

插件名称/
└── agents/
    ├── analyzer.md
    ├── reviewer.md
    └── generator.md

所有.md文件在agents/中自动发现。

命名空间

代理自动命名空间：

单个插件：代理名称
带子目录：插件:子目录:代理名称

测试代理

测试触发

创建测试场景以验证代理正确触发：

编写带具体触发示例的代理
在测试中使用类似表述的示例
检查Claude加载代理
验证代理提供预期功能

测试系统提示

确保系统提示完整：

给代理典型任务
检查是否遵循过程步骤
验证输出格式正确
测试提示中提到的边缘案例
确认满足质量标准

快速参考

最小代理

---
name: 简单代理
description: 当...时使用此代理。示例：<example>...</example>
model: inherit
color: blue
---

您是执行[X]的代理。

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

输出：[提供内容]

Frontmatter字段摘要

字段	必需	格式	示例
name	是	小写连字符	code-reviewer
description	是	文本 + 示例	当…时使用 <example>…
model	是	inherit/sonnet/opus/haiku	inherit
color	是	颜色名称	blue
tools	否	工具名称数组	[“Read”, “Grep”]

最佳实践

应做：

✅ 在描述中包括2-4个具体示例
✅ 编写具体触发条件
✅ 除非特定需要，否则使用inherit模型
✅ 选择适当工具（最小权限）
✅ 编写清晰、结构化的系统提示
✅ 彻底测试代理触发

不应做：

❌ 使用无示例的泛化描述
❌ 省略触发条件
❌ 给所有代理相同颜色
❌ 授予不必要的工具访问
❌ 编写模糊的系统提示
❌ 跳过测试

额外资源

参考文件

详细指南，请查阅：

references/system-prompt-design.md - 完整系统提示模式
references/triggering-examples.md - 示例格式和最佳实践
references/agent-creation-system-prompt.md - Claude Code中的确切提示

示例文件

examples/中的工作示例：

agent-creation-prompt.md - AI辅助代理生成模板
complete-agent-examples.md - 不同用例的完整代理示例

实用脚本

scripts/中的开发工具：

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

实施工作流程

为插件创建代理：

定义代理目的和触发条件
选择创建方法（AI辅助或手动）
创建agents/代理名称.md文件
编写包含所有必需字段的frontmatter
编写系统提示，遵循最佳实践
在描述中包括2-4个触发示例
使用scripts/validate-agent.sh验证
用真实场景测试触发
在插件README中记录代理

关注清晰的触发条件和全面的系统提示以实现自主操作。