技能中心 · 技能管理

技能用于将一套可以重复使用的任务方法封装成能力包，供 AI 应用加载和使用。

一个技能不仅可以告诉 AI“要做什么”，还可以通过 SKILL.md 说明“什么时候使用、按照什么步骤执行、需要参考哪些资料、最终应当输出什么”。支持插入技能、工具（插件、MCP、工作流、三方服务）、知识库、接口资源。

例如，可以将以下任务分别封装成技能：

• 按统一规则解读检查报告；
• 对患者描述进行导诊安全分流；
• 根据固定模板生成病历摘要；
• 调用业务工具查询医生排班；
• 将原始材料整理成标准汇报文档。

简单理解：提示词通常解决一个应用中的角色和回答要求；技能则把一套可以反复使用的任务方法打包起来，让多个 Agent 复用。

一、什么时候应该使用技能

当一项任务具有明确的方法、步骤或输出标准，并且可能被多个应用重复使用时，适合创建技能。

1.1 适合使用技能

可以从下面四个信号判断一项能力是否值得封装成技能：

• 任务反复出现：同类工作已经做过多次，或者多个 Agent 都需要执行，例如每次都要生成相同结构的病历摘要；
• 结果需要统一：希望不同时间、不同应用都遵守相同的业务口径、格式和安全要求；
• 处理方法已经成熟：任务有相对稳定的检查顺序、判断规则或交付标准，不再依赖临时发挥；
• 经验需要复用：团队已经积累了可复用的规范、模板或最佳实践，希望集中维护并提供给更多应用使用。

此外，如果任务需要同时使用说明文档、模板、脚本或工具，也适合通过技能把这些材料组织成一套完整能力。

例如，“检查报告通俗解读”可能同时用于患者服务助手、医生工作助手和报告查询应用。将其制作成技能后，只需要维护一套规则。

1.2 不一定需要使用技能

以下情况通常可以使用更简单的能力：

能力	主要解决什么问题	与技能的区别
提示词	规定当前应用的角色、语气、回答原则或一次任务要求	提示词侧重告诉模型“怎样回答”；技能侧重封装一套可复用的任务方法
知识库	为 AI 提供制度、指南、业务资料等事实依据	知识库侧重提供“参考什么”；技能还会规定“什么时候用、按照什么步骤处理”
工具	查询数据、调用接口或执行一个明确的外部操作	工具提供可执行动作；技能可以说明在什么场景、按什么顺序使用这些动作
工作流	用节点、条件和分支严格控制执行过程	工作流负责确定性的流程编排；技能为 Agent 提供可理解、可按需采用的任务方法
技能	复用一套包含使用条件、执行步骤、输出标准和支持文件的能力	技能可以组合提示词、资料、工具和模板，但不替代它们各自的作用

技能可以引用知识库、工具和其他资源，但它们不是同一种能力。

二、技能怎样被应用使用

技能的使用链路如下：

技能发布后，可以在 Agent 或 AgentLite 的编排页面中加载。

应用运行时会读取技能文件，理解技能的用途和执行要求，并在符合使用条件时按照技能说明完成任务。

Agent 和 AgentLite 均支持加载技能。

三、创建技能前，先想清楚四件事

不要急着打开编辑器。一个容易被正确使用的技能，至少要先明确以下内容。

3.1 它解决什么问题

用一句话说清楚技能的目标。

不够清楚：

处理医疗报告。

更加清楚：

将医学检查报告转换为患者容易理解的说明，同时保留关键指标、异常提示和就医建议边界。

3.2 什么时候应该使用

说明哪些用户请求或业务场景应该触发这个技能。

例如：

• 用户上传检查报告并要求解读；
• 用户询问报告中的指标含义；
• 应用需要生成面向患者的通俗报告摘要。

同时也要说明不应使用的场景，例如资料不完整、无法识别报告类型，或者用户要求直接给出诊断结论。

3.3 执行时需要什么

明确技能需要的输入和依赖：

• 用户输入的文字；
• 上传的文件；
• 知识库；
• 工具或业务接口；
• 输出模板；
• 其他参考资料。

3.4 最终应当得到什么

提前定义输出结构和完成标准。

例如，一份报告解读结果可以包含：

1. 报告基本信息；
2. 关键指标摘要；
3. 异常项目说明；
4. 通俗解释；
5. 风险边界与就医提醒。

如果没有明确的输出标准，同一个技能在不同应用中的结果可能差异很大。

四、技能包的基本结构

技能以一个文件夹为单位，根目录必须包含 SKILL.md。

一个常见的技能目录可以这样组织：

report-explanation/
├─ SKILL.md                 # 必需：技能的核心说明
├─ examples/                # 可选：输入和输出示例
│  ├─ input.md
│  └─ output.md
├─ templates/               # 可选：可复用的输出模板
│  └─ report-template.md
└─ resources/               # 可选：参考文档、脚本或其他素材
   └─ terminology.md

各部分的作用如下：

内容	是否必需	作用
SKILL.md	是	定义技能名称、描述、适用场景和执行方法
examples/	否	帮助 AI 理解输入形式和预期结果
templates/	否	保存需要重复使用的输出结构
resources/	否	保存参考文档、脚本或其他辅助资料

文件夹名称不必完全照搬示例，应当根据实际技能内容组织。简单技能可以只有一个 SKILL.md；内容复杂时，再增加支持文件。

五、怎样编写

SKILL.md 是技能的核心文件。它通常包含两部分：

1. 顶部元数据：告诉平台技能叫什么、主要做什么；
2. Markdown 正文：告诉 AI 什么时候使用，以及如何完成任务。

5.1 基础模板

下面以“检查报告通俗解读”技能为例：

---
name: report-explanation
description: 将医学检查报告转换为患者容易理解的说明，适用于报告解读、指标解释和异常项目摘要。
---

# 检查报告通俗解读

## 适用场景

当用户上传医学检查报告，或要求解释报告中的指标、异常项和专业术语时，使用本技能。

以下情况不要直接执行：

- 报告内容无法识别；
- 缺少完成任务所需的关键页面；
- 用户要求直接给出疾病诊断；
- 用户要求替代医生制定治疗方案。

## 所需输入

执行前确认已经获得：

- 完整的报告文字或文件；
- 报告类型；
- 用户希望重点了解的问题。

如果关键信息缺失，应先向用户询问，不要自行补充。

## 执行步骤

1. 识别报告类型和基本信息。
2. 提取关键指标及其结果。
3. 标记报告中已经明确提示的异常项目。
4. 使用通俗语言解释专业术语。
5. 区分“报告原文结论”和“辅助说明”。
6. 按指定格式生成结果。
7. 添加必要的医疗安全提醒。

## 输出格式

按照以下顺序输出：

1. 报告摘要
2. 关键指标
3. 异常项目说明
4. 通俗解释
5. 注意事项

## 约束

- 不得根据单份报告直接作出疾病诊断。
- 不得虚构报告中不存在的指标或结果。
- 不得擅自推荐处方药物或治疗方案。
- 无法确认的信息必须明确标注。
- 涉及紧急风险时，应建议用户及时联系专业医务人员。

## 示例

输入和输出示例见 `examples/` 文件夹。

这不是所有技能必须照抄的固定格式，但一个完整技能通常应回答：

• 它是什么；
• 什么时候使用；
• 需要什么输入；
• 按什么步骤执行；
• 输出什么结果；
• 有哪些限制；
• 什么才算完成。

5.2 名称怎样写

name 是技能的稳定标识。

建议：

• 使用能够表达任务含义的英文名称；
• 使用字母、数字、连字符或下划线；
• 保持简短、稳定；
• 不要把版本号写进名称。

推荐：

name: report-explanation

不推荐：

name: skill-001

skill-001 无法让维护者判断技能用途。

5.3 description 怎样写

description 不只是展示给用户看的简介，它还承担“告诉 AI 这个技能能做什么、什么时候可能使用”的作用。

建议同时包含：

• 核心能力；
• 主要使用场景；
• 与相似技能的区别。

不够清楚：

description: 一个报告技能。

更加清楚：

description: 将医学检查报告转换为患者容易理解的说明，适用于报告解读、指标解释和异常项目摘要。

描述应当准确，不要为了让技能更容易被调用而写成“适用于所有任务”。范围过宽会增加误用。

5.4 执行步骤怎样写

执行步骤应使用清晰、可以实际执行的指令。

不推荐：

请认真分析报告并给出专业回答。

这句话没有说明怎样分析，也没有定义什么是“专业回答”。

推荐：

1. 提取报告中的检查项目、结果和参考范围。
2. 只标记报告中明确超出参考范围的项目。
3. 使用通俗语言解释异常项目。
4. 将报告原文结论与辅助说明分开呈现。

编写时遵循以下原则：

• 一个步骤只描述一个主要动作；
• 按实际执行顺序排列；
• 明确需要检查的条件；
• 明确遇到信息缺失时怎么办；
• 不依赖“适当处理”“自行判断”等模糊表述；
• 涉及风险操作时说明是否需要人工确认。

5.5 示例有什么作用

示例可以让 AI 更准确地理解预期输入和输出。

适合提供示例的情况包括：

• 输出格式要求严格；
• 输入形式比较复杂；
• 容易混淆正确与错误结果；
• 需要保持统一语气；
• 需要展示边界情况。

示例不应只展示最理想的情况。条件允许时，可以同时提供正常输入、信息缺失、不应执行和正确输出等示例。

六、在平台中创建技能

进入 技能中心 → 技能管理，点击右上角的 添加技能。

平台提供两种创建方式：

• 自定义创建：在平台中从零编写技能；
• 导入技能：上传已有技能包。

6.1 自定义创建

自定义创建按照以下流程进行：

填写基础信息 → 构建技能 → 技能设置 → 技能发布

第一步：填写基础信息

字段	说明
技能图标	用于技能列表展示；不上传时使用默认图标
技能名称	展示给用户看的名称
技能标识	技能的稳定标识，必须以字母开头
技能描述	说明技能的能力和使用场景
技能分组	选择技能所属分组

技能名称用于展示，技能标识用于识别。两者可以表达相同含义，但技能标识应保持稳定。

第二步：构建技能

构建页面左侧是文件树，右侧是文件编辑和预览区域。

你可以：

• 编辑根目录中的 SKILL.md；
• 新建文件或文件夹；
• 上传支持文件；
• 引用技能、工具、知识库和数据资源；
• 在文本视图和 Markdown 源码视图之间切换。

编写时应先完成最小可运行版本：

1. 写清楚技能用途；
2. 写清楚使用条件；
3. 写出可执行步骤；
4. 定义输出；
5. 补充必要限制。

确认最小版本能够正常完成任务后，再增加模板、示例和其他支持文件。

第三步：确认技能设置

检查名称、标识、描述、图标和分组是否准确。

特别检查技能描述。描述过于笼统，可能导致使用者看不懂技能用途；描述范围过宽，也可能导致技能被用于不合适的任务。

第四步：发布技能

填写版本号和版本说明，然后点击 保存并发布。

建议使用清晰的版本规则：

• 1.0.0：第一个正式可用版本；
• 1.0.1：修正文案、示例或小问题；
• 1.1.0：增加新的使用场景或能力；
• 2.0.0：执行规则或输出发生不兼容变化。

版本说明应记录“改了什么、为什么改、可能影响什么”，不要只写“更新技能”。

6.2 导入技能

导入适用于已经准备好技能包的情况。

导入文件应为 zip 或 .skill 文件，并在根目录包含 SKILL.md。

skill-name/
├─ SKILL.md
└─ 其他可选文件

操作步骤：

1. 点击 添加技能 → 导入技能；

2. 上传技能文件；

   

3. 等待平台读取 SKILL.md；

4. 检查自动填充的名称、标识和描述；

5. 选择图标和分组；

6. 点击 确定导入。

如果导入失败，优先检查：

• SKILL.md 是否位于技能包根目录；
• YAML 是否使用正确的 --- 包围；
• 是否包含 name 和 description；
• YAML 缩进和冒号是否正确；
• 压缩包外层是否多套了一层无关目录。

七、发布前怎样验证技能

技能能够保存，不代表技能已经写好。发布前至少完成以下检查。

7.1 内容检查

• 名称能否准确表达用途；
• 描述是否说明功能和使用场景；
• 使用条件是否清楚；
• 执行步骤是否可以逐条完成；
• 输入不足时是否说明处理方式；
• 输出结构是否明确；
• 是否包含必要的禁止事项和安全边界；
• 正文引用的文件是否真实存在。

7.2 场景测试

至少准备三类测试：

测试类型	目的
正常场景	验证技能能否完成主要任务
信息缺失场景	验证技能是否会先询问，而不是编造内容
不适用或高风险场景	验证技能是否会拒绝越界执行或要求人工确认

医疗技能还应重点检查：

• 是否虚构医疗事实；
• 是否混淆报告原文与 AI 解释；
• 是否给出未经授权的诊断或处方；
• 是否泄露患者敏感信息；
• 高风险操作是否保留人工确认。

7.3 在应用中联调

技能发布后，将它加载到 Agent 应用中，通过预览与调试功能进行真实测试。

测试时观察：

1. 适用场景下能否正确使用技能；
2. 不适用场景下是否会错误使用；
3. 技能能否读取所需支持文件；
4. 引用的工具或知识库是否正常；
5. 输出是否符合技能规定；
6. 多轮对话中是否能持续遵守限制。

如果结果不符合预期，应优先检查 description、适用场景、执行步骤和输出要求，而不是单纯增加更多文字。

八、管理已有技能

技能管理首页用于查找和维护已经创建的技能。

8.1 查找技能

可以通过以下方式定位技能：

• 按分组查看；
• 按官方技能或用户技能筛选；
• 按自定义创建或导入技能筛选；
• 按技能名称搜索。

技能较少时不必提前设计复杂分组。技能数量增加后，再按照业务领域、服务对象或能力类型整理。

8.2 查看和编辑

点击技能卡片可以查看技能详情。

点击 编辑技能，可以修改技能文件并发布新版本。历史版本会保留，不需要复制整个技能作为备份。

8.3 管理版本

版本页面可以查看：

• 技能基本信息；
• 已发布版本；
• 每个版本包含的文件；
• 当前最新版本；
• 将指定的历史版本还原为新版本。

需要还原版本时，在左侧的技能版本列表中选择目标版本，确认该版本包含的文件和内容后，点击右上角的 还原版本。填写新版本号和版本描述，然后点击 确定。

还原完成后，平台会基于所选历史版本创建一个新版本，并将其标记为最新版本。原有版本仍会保留。

修改已经投入使用的技能前，应确认哪些应用正在引用它，并评估新版本是否会改变原有执行结果。

8.4 设置、复制和删除

• 技能设置：修改名称、描述、图标和分组，不修改技能文件；
• 复制技能：创建独立副本，用于基于现有能力开发新技能；
• 删除技能：永久删除技能。

删除技能时，平台不会校验技能是否被应用引用，确认后将直接删除，且删除操作不可恢复。

九、一个好技能的判断标准

一个好的技能不取决于文件多少，而取决于 AI 能否稳定理解和执行。

可以使用下面五个问题进行判断：

1. 找得到：名称和描述能否让人快速理解用途？
2. 用得对：是否说明了使用和不使用的条件？
3. 做得完：执行步骤是否清楚、完整、可操作？
4. 结果稳：是否定义了输出结构和完成标准？
5. 不越界：是否包含权限、隐私和业务安全限制？

如果这五个问题都能得到明确答案，技能才具备被多个应用稳定复用的基础。