⚡

代理开发Skill agent-development

Claude Code插件代理开发指南，提供AI智能体创建、配置、触发条件、系统提示设计、最佳实践等完整开发框架。关键词：AI智能体开发，Claude插件，代理配置，系统提示设计，触发条件，自主代理，AI工具开发，智能体框架

AI智能体 0 次安装 0 次浏览 更新于 3/1/2026

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

Claude Code插件的代理开发

概述

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

关键概念：

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

代理文件结构

完整格式

---
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何时应触发此代理。这是最关键字段。

必须包括：

  1. 触发条件 (“当…时使用此代理”)
  2. 多个<example>块展示用法
  3. 每个示例中的情境、用户请求和助手响应
  4. <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：手动创建

  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. 确认满足质量标准

快速参考

最小代理

---
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 - 测试代理是否正确触发

实施工作流程

为插件创建代理：

  1. 定义代理目的和触发条件
  2. 选择创建方法 (AI辅助或手动)
  3. 创建agents/agent-name.md文件
  4. 编写包含所有必需字段的前置元数据
  5. 按照最佳实践编写系统提示
  6. 在描述中包含2-4个触发示例
  7. 使用scripts/validate-agent.sh验证
  8. 使用真实场景测试触发
  9. 在插件README中记录代理

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