name: 代理开发 description: 此技能应在用户请求“创建代理”、“添加代理”、“编写子代理”、“代理前端元数据”、“何时使用描述”、“代理示例”、“代理工具”、“代理颜色”、“自主代理”，或需要关于代理结构、系统提示、触发条件或Claude代码插件代理开发最佳实践的指导时使用。 version: 0.1.0

Claude代码插件的代理开发

概述

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

关键概念：

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

代理文件结构

完整格式

---
name: agent-identifier
description: 在[触发条件]时使用此代理。示例：

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

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

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

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

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

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

**输出格式：**
[提供什么]

前端元数据字段

name（必需）

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

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

良好示例：

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

不良示例：

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

description（必需）

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

必须包括：

触发条件（“在…时使用此代理…”）
多个<example>块显示用法
每个示例中的情境、用户请求和助手响应
<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": "agent-name",
  "whenToUse": "在...时使用此代理。示例：<example>...</example>",
  "systemPrompt": "您是...”
}

然后转换为带前端元数据的代理文件格式。

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

方法2：手动创建

选择代理标识符（3-50个字符、小写、连字符）
编写带示例的描述
选择模型（通常inherit）
选择颜色用于视觉识别
定义工具（如果限制访问）
按上述结构编写系统提示
保存为agents/agent-name.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个字符 结构： 清晰的职责、流程、输出格式

代理组织

插件代理目录

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

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

命名空间

代理自动命名空间：

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

测试代理

测试触发

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

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

测试系统提示

确保系统提示完整：

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

快速参考

最小代理

---
name: simple-agent
description: 在...时使用此代理。示例：<example>...</example>
model: inherit
color: blue
---

您是一个代理，[执行X]。

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

输出：[提供什么]

前端元数据字段摘要

字段	必需	格式	示例
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/agent-name.md文件
编写包括所有必需字段的前端元数据
遵循最佳实践编写系统提示
在描述中包括2-4个触发示例
使用scripts/validate-agent.sh验证
用真实场景测试触发
在插件README中记录代理

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