--- name: agent-development description: 当用户要求“创建智能体”、“添加智能体”、“编写子智能体”、“智能体前置元数据”、“何时使用描述字段”、“智能体示例”、“智能体工具”、“智能体颜色”、“自主智能体”，或需要关于Claude Code插件智能体结构、系统提示词、触发条件或智能体开发最佳实践的指导时，应使用此技能。 version: 0.1.0 --- # Claude Code插件智能体开发 ## 概述智能体是处理复杂、多步骤任务的自主子进程。理解智能体结构、触发条件和系统提示词设计，能够创建强大的自主功能。 **核心概念：** - 智能体用于自主工作，命令用于用户发起的操作 - 采用包含YAML前置元数据的Markdown文件格式 - 通过包含示例的描述字段触发 - 系统提示词定义智能体行为 - 模型和颜色可自定义 ## 智能体文件结构 ### 完整格式 ```markdown --- name: agent-identifier description: 当[触发条件]时使用此智能体。示例：上下文：[情境描述] 用户：“[用户请求]” 助手：“[助手应如何响应并使用此智能体]” [为何应触发此智能体] [更多示例...] 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何时应触发此智能体。**这是最关键的字段。** **必须包含：** 1. 触发条件（“当...时使用此智能体”） 2. 多个``块展示用法 3. 每个示例中的上下文、用户请求和助手响应 4. ``解释为何触发智能体 **格式：** ``` 当[条件]时使用此智能体。示例：上下文：[场景描述] 用户：“[用户所说内容]” 助手：“[Claude应如何响应]” [为何此智能体适用] [更多示例...] ``` **最佳实践：** - 包含2-4个具体示例 - 展示主动和被动触发 - 涵盖相同意图的不同表达方式 - 在评论中解释推理 - 具体说明何时不应使用该智能体 ### model（必填）智能体应使用的模型。 **选项：** - `inherit` - 使用与父级相同的模型（推荐） - `sonnet` - Claude Sonnet（平衡） - `opus` - Claude Opus（能力最强，昂贵） - `haiku` - Claude Haiku（快速，便宜） **推荐：** 除非智能体需要特定模型能力，否则使用`inherit`。 ### color（必填） UI中智能体的视觉标识符。 **选项：** `blue`, `cyan`, `green`, `yellow`, `magenta`, `red` **指南：** - 为同一插件中的不同智能体选择不同颜色 - 为相似类型的智能体使用一致的颜色 - 蓝色/青色：分析、审查 - 绿色：面向成功的任务 - 黄色：谨慎、验证 - 红色：关键、安全 - 洋红色：创意、生成 ### tools（可选）将智能体限制为特定工具。 **格式：** 工具名称数组 ```yaml tools: ["Read", "Write", "Grep", "Bash"] ``` **默认：** 如果省略，智能体有权访问所有工具 **最佳实践：** 将工具限制在所需的最小范围（最小权限原则） **常见工具集：** - 只读分析：`["Read", "Grep", "Glob"]` - 代码生成：`["Read", "Write", "Grep"]` - 测试：`["Read", "Bash", "Grep"]` - 完全访问：省略字段或使用`["*"]` ## 系统提示词设计 Markdown正文成为智能体的系统提示词。以第二人称书写，直接对智能体说话。 ### 结构 **标准模板：** ```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个``块展示何时使用返回JSON： { "identifier": "agent-name", "whenToUse": "当...时使用此智能体。示例：...", "systemPrompt": "你是..." } ``` 然后转换为带前置元数据的智能体文件格式。查看`examples/agent-creation-prompt.md`获取完整模板。 ### 方法2：手动创建 1. 选择智能体标识符（3-50个字符，小写，连字符） 2. 编写包含示例的描述 3. 选择模型（通常为`inherit`） 4. 选择用于视觉识别的颜色 5. 定义工具（如果限制访问） 6. 按上述结构编写系统提示词 7. 保存为`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` ## 测试智能体 ### 测试触发创建测试场景以验证智能体是否正确触发： 1. 编写具有特定触发示例的智能体 2. 在测试中使用与示例相似的措辞 3. 检查Claude是否加载了该智能体 4. 验证智能体是否提供预期功能 ### 测试系统提示词确保系统提示词完整： 1. 给智能体典型任务 2. 检查其是否遵循流程步骤 3. 验证输出格式是否正确 4. 测试提示词中提到的边缘情况 5. 确认满足质量标准 ## 快速参考 ### 最小化智能体 ```markdown --- name: simple-agent description: 当...时使用此智能体。示例：... model: inherit color: blue --- 你是[做X事]的智能体。流程： 1. [步骤1] 2. [步骤2] 输出：[提供内容] ``` ### 前置元数据字段摘要 | 字段 | 必填 | 格式 | 示例 | |-------|----------|--------|---------| | name | 是 | 小写-连字符 | code-reviewer | | description | 是 | 文本 + 示例 | 当...时使用 ... | | 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`** - 测试智能体是否正确触发 ## 实施工作流为插件创建智能体： 1. 定义智能体目的和触发条件 2. 选择创建方法（AI辅助或手动） 3. 创建`agents/agent-name.md`文件 4. 编写包含所有必填字段的前置元数据 5. 遵循最佳实践编写系统提示词 6. 在描述中包含2-4个触发示例 7. 使用`scripts/validate-agent.sh`验证 8. 用真实场景测试触发 9. 在插件README中记录智能体专注于清晰的触发条件和全面的系统提示词以实现自主操作。


名称	模板技能
描述	替换为技能的描述以及Claude应何时使用它。

在下方插入指令