创建和维护可复用的 Skill

连接 AI 助手

在智能体开发服务平台（AgentWorks）中，Skill 是包含 SKILL.md 和相关文件的版本化工作说明包。例如，一个数据交付验收 Skill 可以同时保存验收步骤、字段检查清单、错误分类规则和报告示例；智能体只在处理相关任务时加载这些内容，不必把整套方法始终放在系统提示词中。

Skill 不是可直接执行的工具；它为智能体提供完成任务的方法和资源。需要调用 API、运行命令或执行脚本时，还要为智能体配置相应的 MCP、平台工具包、用户工具包或沙箱。

只有关联了技能组的智能体才能使用其中的 Skill。技能组提供候选 Skill；智能体真正读取 Skill 时，运行时再根据 stable 和 latest 标记解析版本。技能组不会在每次请求中自动激活组内全部 Skill。

判断任务是否适合使用 Skill

当一套任务方法需要复用、按需加载、随文件一起管理或保留明确版本时，使用 Skill。根据任务真正缺少的能力选择合适方式：

任务需要	优先选择	原因
每次请求都必须遵守的简短行为规则	系统提示词	规则始终进入智能体上下文，不需要按任务选择
只在特定任务中使用的步骤、方法、检查清单或模板	Skill	智能体可以根据任务按需加载，并按版本复用
从大量资料中检索事实或原文	知识库	知识库用于检索内容，Skill 用于说明怎样完成任务
调用外部 API、业务系统或服务	MCP、平台工具包或用户工具包	工具执行操作，Skill 可以说明何时以及怎样调用它
运行命令、脚本或处理文件	沙箱	沙箱提供执行环境；Skill 可以提供脚本、步骤和输入说明

一个任务可以同时使用 Skill 和其他能力。例如，Skill 可以说明如何检查 CSV 文件，沙箱负责实际运行检查脚本，MCP 负责把验收结果写回外部系统。

理解智能体如何使用 Skill

Skill 不会因为已经创建就自动进入智能体。先把 Skill 加入技能组，再把技能组实例或模板关联到智能体模板。智能体处理请求时，会根据可用 Skill 的名称和描述判断是否需要加载其中一个；确定需要后，运行时再解析并读取相应版本。

图表预览

三个分栏依次展示 Skill 的提供与选择、内容加载和操作执行。每个分栏中的判断都是可选分支：当前请求不一定需要 Skill，激活后不一定需要读取其他资源，处理任务时也不一定需要调用工具或沙箱。

注意

修改文件副本不会更新平台上的 Skill

平台提供给智能体使用的 Skill 文件是只读的。对话中生成的修改稿，或对可写副本的修改，都不会自动更新平台上的 Skill 或创建新版本。需要采用修改时，按维护 Skill中的说明检查并在控制台保存。

创建或导入 Skill

可以在控制台中从零创建 Skill，也可以导入 ZIP 或从 Skills 广场克隆已有内容。无论从哪里取得内容，都应先完成审查，再提供给智能体使用。

注意

不支持指定额外的 OSS Skill 目录

AgentWorks 不支持将 OSS 或其他外部目录配置为额外的 Skill 来源。沙箱挂载对象存储只提供文件访问，不会把其中的文件自动变成平台 Skill。需要按平台 Skill 使用时，请将文件打包为 ZIP 导入，再加入技能组。

使用有权创建或修改 Skill 的账号完成以下操作。遇到权限提示时，请联系管理员按排查权限问题检查授权。

1. 打开 Skills 管理。

   打开 Skill 管理

创建一个 Skill

1. 选择 新建 Skill，填写便于识别的名称和描述，并提供初始 SKILL.md。

   注意

   名称按 3–32 个字符填写

   Skill 名称使用英文、数字、连字符和下划线，长度为 3–32 个字符。即使输入框允许输入更长的名称，也请遵守这个范围；超过 32 个字符会在保存时被拒绝。

2. 选择 创建，再打开新建的 Skill。

   注意

   创建 Skill 时会自动生成 v1

   AgentWorks 会同时创建 Skill 和它的第一个版本 v1。新建表单中的 SKILL.md 内容会保存到 v1；即使没有填写内容，仍会生成一个内容为空的 v1。v1 会成为当时的 latest，因此不需要为了完成首次创建再选择一次 新版本。

3. 确认版本列表中已经显示 v1。

4. 需要附带其他资源时，在 文件 中上传文件，或通过 新建文件 创建文本文件。

5. 检查 SKILL.md 中引用的相对路径能够找到 v1 中的对应文件，再把这个 Skill 加入测试技能组。

文本文件可以在线编辑和删除；二进制文件不能在线编辑。脚本文件可以作为 Skill 资源保存，但不会因为上传到 Skill 而自动执行、安装依赖或注册为工具。

创建新版本

新版本号由平台自动递增，不能手动填写。例如，当前最高版本是 v1 时，下一次创建、克隆或上传得到的版本就是 v2。新版本会成为 latest；此前的版本仍然保留，但不再带有 latest 标记。

将当前编辑的 SKILL.md 保存为新版本

1. 打开目标 Skill，并在左侧选择要作为参考的版本。

2. 打开 SKILL.md，确认编辑器中是新版本需要保存的完整内容。

3. 选择 新版本。

   注意

   “新版本”只保存 SKILL.md，不复制其他文件

   这项操作只使用当前编辑器中的 SKILL.md。原版本中的脚本、配置、图片和参考文件仍然保留，但不会带入新版本；智能体使用新版本时，也不会自动从旧版本读取这些文件。

   需要保留这些文件时，请取消操作，改为选择原版本的 克隆，把 SKILL.md 和其他文件一起复制到下一个版本，再修改并保存。

4. 按需填写新版本信息：

   • 描述：说明本次版本修改了什么，便于以后选择和回退。
   • 分支：记录该版本对应的代码分支或维护线；这个字段只保存说明，不会连接或同步 Git 分支。
   • 创建人：记录本次版本的维护者。
   • 标记为 stable：表示团队把这个版本标记为稳定版本。只在完成内容审查和测试后选择。

   这些字段均为可选字段。版本号和 latest 状态由平台自动设置。

5. 确认后创建版本。

6. 打开新版本，核对版本号、SKILL.md 和文件列表，再在不会影响现有使用者的环境中验证。

上传 ZIP 作为新版本

1. 准备包含 SKILL.md 和所有需要保留文件的完整 ZIP。

   上传 ZIP 不会与旧版本合并。推荐让 SKILL.md 直接位于 ZIP 根目录，并把脚本、配置和参考资料放在相对于它的子目录中：

   skill-version.zip
   ├── SKILL.md
   ├── scripts/
   │   └── run.py
   └── references/
       └── checklist.md

   ZIP 也可以只包含一个顶层目录，并把同样的结构放在该目录中，例如 my-skill/SKILL.md。不要在一份 ZIP 中放入多个 Skill 根目录。

2. 在 SKILL.md 第一行开始编写 YAML frontmatter。Frontmatter 是两条 --- 之间的版本元数据；后面的 Markdown 才是智能体读取的任务说明。例如：

   ---
   name: data-validation
   description: 检查交付数据的结构和内容
   ---
   
   # 数据检查方法

   字段	填写要求
   name	ZIP 导入时必填。使用普通字符串，只能包含 3–32 位英文、数字、连字符（-）或下划线（_）。上传新版本时，建议与当前 Skill 的名称保持一致。
   description	建议填写一句清楚的用途说明。使用普通字符串；平台不要求必填。
   其他字段	只有相应功能文档明确说明时再使用。字段能够保存，不代表 AgentWorks 一定会读取或执行它。

   注意

   Skill 名称不取自 ZIP 文件名

   请继续使用 .zip 后缀，方便识别和选择文件。创建新 Skill 时，平台从 SKILL.md 的 name 读取名称；上传新版本时，版本会加入当前打开的 Skill。ZIP 文件名和外层目录名都不会改变 Skill 名称。

3. 上传前检查 ZIP：

   • ZIP 中只保留一个 Skill 根目录。
   • SKILL.md 的大小写完全一致。
   • SKILL.md 位于 ZIP 根目录，或唯一顶层目录的根部。
   • SKILL.md 使用 UTF-8。
   • Frontmatter 的起止 --- 完整。
   • name 和 description 都使用普通字符串。
   • 引用的脚本和资料位于同一 Skill 根目录，并使用相对路径。不要在 ZIP 条目中使用绝对路径或 ..。

4. 打开目标 Skill，选择 上传新版本，再选择准备好的 ZIP。

5. 确认平台生成了下一个版本号，并检查 SKILL.md、相关文件和 latest 标记。

   注意

   上传成功后仍要检查 Skill 内容

   平台会检查 ZIP 是否可以读取、是否包含 SKILL.md，以及 name 是否符合格式要求。平台不会替你确认 SKILL.md 引用的文件是否存在、脚本是否安全可用，或所需工具是否已经提供给智能体。请打开新版本检查文件列表，再通过测试技能组验证。

需要快速取得可用的 ZIP 结构时，可以先对一个现有版本选择 导出 zip，在导出的文件中修改内容后，再作为新版本上传。

ZIP 上传失败时检查

• 提示找不到 SKILL.md：检查文件名大小写和所在目录。
• 提示缺少 name：确认 frontmatter 位于文件开头，并包含非空的 name。
• 提示名称格式不正确：改用 3–32 位英文、数字、连字符（-）或下划线（_）。
• 提示 ZIP 无效：重新压缩 Skill 目录，不要上传其他归档格式或空文件。
• 提示目标 Skill 不存在或无法访问：确认当前账号可以管理该 Skill，并从其详情页重新选择 上传新版本。

通过 ZIP 或 Skills 广场创建 Skill

以下入口会创建另一个 Skill，而不是为当前打开的 Skill 增加版本。需要增加版本时，请使用前面的 上传新版本。

• 在 Skills 管理 中，可以通过 导入 zip（新建 Skill） 创建 Skill。

• 在 Skills 广场 中搜索目标 Skill，再选择 克隆。

  打开 Skills 广场

导入或克隆后，逐个检查 SKILL.md、脚本、配置和附带文件。不要把密钥、个人数据或未经审查的可执行内容加入 Skill。广场提供发现和克隆入口，不表示内容已经通过当前租户的安全或业务审批。

需要在环境间审查或迁移时，可以通过 导出 zip 保存版本文件。导出物可能包含脚本和业务内容，请按组织的软件制品要求保存和传递。

编写便于准确激活的 Skill

智能体先根据 Skill 的名称和描述判断是否需要加载它，再读取运行时解析出的版本。名称和描述应明确区分任务；多个 Skill 的适用范围高度重叠时，智能体可能无法稳定选择预期 Skill。

在 SKILL.md 中写明：

• 这个 Skill 适用于什么任务，以及不适用于什么任务。
• 开始任务前需要具备哪些输入或前提条件。
• 应按什么步骤完成任务。
• 完成后应得到什么结果，以及怎样判断结果正确。
• 需要读取哪些相关文件、文件中包含什么内容，以及何时使用。
• 如果步骤依赖工具或沙箱，应调用什么能力并检查什么执行结果。

加入技能组后，分别使用明确匹配、不匹配以及可能匹配相邻 Skill 的输入进行测试。这样可以同时检查目标 Skill 能否被激活，以及它是否会在无关任务中被误选。

让运行中的智能体使用经过验证的 Skill 版本

先记录目标 Skill、技能组中的版本选择和用于核对内容的样例，再在独立测试实例中验证。Skill 说明与资源的读取、沙箱中挂载的文件是两条使用路径，应分别确认版本，不能仅凭一个版本标记判断两条路径都已更新。

理解版本标记怎样影响模板和实例

智能体模板通过技能组确定可使用哪些 Skill。技能组中的版本选择会用于沙箱文件准备；智能体通过 Skill 能力读取说明和资源时，不把该选择作为所有读取路径的固定版本。stable 和 latest 是 Skill 的版本标记，变更标记后也应重新核对实际读取结果。

图表预览

同一任务可能先读取 Skill 说明，再执行沙箱中的脚本。两处内容都应来自本次验证的版本；只检查说明或只检查文件，可能遗漏另一条路径的差异。

比较版本操作的影响

操作	保存的配置变化	更新后检查
创建新版本	新版本成为 latest	现有智能体读取的说明和资源是否改变
设置或取消 stable	改变 Skill 的稳定版本标记	所有引用方的实际读取结果
修改技能组版本选择	改变技能组保存的版本配置	更新实例后，沙箱文件与目标版本是否一致
修改技能组模板	改变以后创建或更新实例时应用的组合	目标智能体更新后的技能组、内容读取和挂载文件

注意

stable 由维护者确认

平台不会自动判断某个版本是否已经通过测试。stable 是人工维护的标记；完成内容检查和运行验证后，再选择 设为 stable。该标记不替代技能组版本选择和实际文件检查。

将新版本投入使用

1. 记录当前经过验证的版本、版本标记、技能组配置和代表性测试结果。
2. 按创建新版本选择合适的方式：克隆现有版本、上传完整 ZIP，或只保存当前编辑器中的 SKILL.md。平台会自动生成版本号并将其标记为 latest。
3. 检查候选版本的 SKILL.md 和文件列表。
4. 在独立的测试 Skill 副本和测试智能体中验证触发条件、资源读取、执行步骤和结果，避免测试期间改变生产使用的共享 Skill。
5. 验证通过后，更新正式 Skill 的版本标记及技能组版本选择；技能组来自模板时，修改来源模板，再编辑并保存目标智能体实例。
6. 使用目标版本独有的说明或资源执行代表性任务，并核对沙箱中实际挂载的文件，确认两条路径符合预期。
7. 如果需要回退，恢复先前记录的版本标记和技能组配置，重新更新实例，再执行同一组回归测试。

将 Skill 提供给智能体

准备好 Skill 内容和版本后，把它加入技能组，再让智能体模板关联相应的技能组实例或模板。Skill 内容、技能组交付方式和执行能力是三个不同层次，应分别验证。

重要

使用 Skill 前，先启用文件读取

在智能体模板的 文件系统 中开启 启用文件系统，并保留 read_file。只需读取 Skill 和参考文件时，建议选择 仅只读；即使不运行脚本，读取 Skill 说明也需要这个设置。

将 Skill 加入技能组

打开使用技能组为智能体提供一组 Skill，完成以下选择和操作：

1. 选择让多个智能体实例共享一个技能组实例，还是分别生成独立技能组。
2. 把目标 Skill 加入相应的技能组实例或模板。
3. 把技能组实例或模板添加到智能体模板，并按步骤启用文件系统、保留 read_file。
4. 创建或更新智能体实例。

让智能体按需激活 Skill

技能组让智能体获得所选 Skill 的名称和描述。处理请求时，智能体按任务选择匹配的 Skill，再通过 read_file 读取对应的 SKILL.md 和需要的资源。能列出 Skill 名称不代表已经读到完整说明；请用目标版本独有的内容检查读取结果。

一次请求不一定需要 Skill，也不会因为技能组中包含多个 Skill 而依次激活全部 Skill。需要稳定触发目标 Skill 时，请使用只有借助该 Skill 才能正确完成的测试输入。

读取 Skill 引用的资源

如果 SKILL.md 引用脚本、配置、参考资料或其他文件，智能体会根据相对于 Skill 根目录的路径找到对应资源，再通过 read_file 读取运行时解析出的版本中的内容：

• SKILL.md：提供任务步骤、适用条件、示例和边界。
• 相关文本资源：在 Skill 说明需要时读取，作为完成任务的输入。
• 脚本文件：可以读取内容，但不会因此自动执行、安装依赖或注册为工具。

SKILL.md 已经包含完成任务所需信息时，智能体不需要继续读取其他资源。

为 Skill 配置执行能力

Skill 资源读取和工具执行是两条独立路径：

• 需要运行命令、脚本或处理沙箱文件时，配置沙箱，确认实际文件路径、运行时和依赖。
• 需要调用外部工具服务时，配置 MCP、平台工具包或用户工具包。
• 只需要复用任务步骤、方法或模板时，关联技能组并启用文件读取即可，不需要额外配置沙箱或外部工具。

同一个智能体模板同时关联技能组和沙箱时，所选 Skill 版本以只读方式挂载到沙箱的 /skills 目录。选择 沙箱 - 模板 时，这个沙箱随智能体实例新建。直接关联已有 沙箱 - 实例 时，挂载仍写到那个共享沙箱的同一个 /skills，不会按智能体分开。文件已经挂载不表示脚本已经执行。

注意

不同 Skill 集合不要共用沙箱实例

后接入的智能体可能覆盖共享沙箱中先前挂上的 Skill 文件。需要不同 Skill 集合的智能体不能通过复用现有沙箱实例取得各自的 Skill 文件，应使用沙箱模板，为各个智能体实例准备自己的沙箱。参见选择沙箱模板或实例。

验证 Skill 激活、资源读取和执行结果

创建或更新智能体实例后，分别检查三个层次：

1. 说明读取：用能明确触发目标 Skill 的输入测试，在 Trace 中确认 read_file 成功读取目标 SKILL.md，并核对返回内容。
2. 资源读取：测试依赖相关文件时，确认 read_file 读取了目标文件，并核对路径和内容。
3. 实际执行：任务需要工具或沙箱时，另外确认工具调用、脚本输出或外部系统结果；Skill 激活本身不能证明操作已经执行。

再用不会触发 Skill 的输入以及可能匹配相邻 Skill 的输入确认边界。使用只存在于目标版本中的短语或样例，可以确认智能体实际解析的 Skill 版本。

注意

Trace 中的 Skill 运行时调用

read_file 也用于读取普通任务文件。看到这个调用名称还不够，应核对它读取的是否为目标 Skill 的文件，以及返回内容是否符合预期。读取脚本内容不会执行脚本，需要另行检查沙箱或其他执行工具的结果。

维护 Skill

智能体可以帮你准备修改稿，你检查后在 Skills 管理 中保存。只修改 SKILL.md 时，可以按下面的步骤操作。

用于正式任务的 Skill，先用独立的测试 Skill 副本验证修改；克隆会生成新版本，并把新版本标为 latest。

1. 让智能体直接输出完整的 SKILL.md 修改稿，保留开头的 YAML 元数据，不必先写入文件。
2. 检查修改稿后，在控制台选择原版本的 克隆，再把修改稿粘贴到克隆版本的 SKILL.md 编辑器中保存。
3. 按将新版本投入使用确认版本选择后，开启新会话，让智能体读取该 Skill，并在 read_file 的返回中核对保存后的内容。

需要修改附带的文本文件时，先克隆包含这些文件的版本，再在新版本的 文件 中编辑并保存。二进制文件不能在线编辑；需要替换二进制文件或批量修改时，可以导出完整 ZIP，修改后上传为新版本。

升级或回退 Skill

升级 Skill 时，按将新版本投入使用记录当前配置，再创建、检查和验证候选版本。需要回退时，恢复版本标记、技能组配置和相关实例，并分别检查内容读取与沙箱文件。

同一个 Skill 可能供多个技能组、智能体模板和智能体实例使用。调整 stable 前应确认所有使用者都可以接受这次变化；需要分阶段发布时，使用独立的测试 Skill 副本或测试租户，不要通过共享 Skill 的标记区分不同批次。

删除 Skill 或版本

删除前检查技能组模板、技能组实例、智能体模板和智能体实例的引用：

• 删除 stable 或 latest 版本会改变运行时的版本选择；删除前先为保留版本设置正确标记并完成回归。
• 删除 Skill 会移除其元信息和版本入口，不能自动修复技能组。

先让运行时可以解析到经过验证的替代版本，并在引用该 Skill 的智能体实例中完成回归，再执行删除。需要保留制品时，先通过 导出 zip 保存到团队批准的制品库。