⚡

智能体开发 agent-development

本技能是关于Claude Code插件中自主智能体（Agent）的开发指南。它详细说明了如何创建、配置和部署用于处理复杂多步骤任务的AI智能体，包括智能体文件结构、前置元数据（YAML frontmatter）规范、系统提示词（System Prompt）设计、触发条件定义、工具权限管理以及最佳实践。核心关键词包括：AI智能体开发、Claude Code插件、系统提示词设计、自主代理、触发条件、工具权限、YAML配置、多步骤任务自动化。

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>
上下文：[情境描述]
用户：“[用户请求]”
助手：“[助手应如何响应并使用此智能体]”
<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>
上下文：[场景描述]
用户：“[用户所说内容]”
助手：“[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中记录智能体

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