创建和维护可复用的 Skill
在智能体开发服务平台（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，也可以导入 ZIP 或从 Skills 广场克隆已有内容。无论从哪里取得内容，都应先完成审查，再提供给智能体使用。
打开 Skills 管理。
创建一个 Skill
选择 新建 Skill，填写便于识别的名称和描述，并提供初始
SKILL.md。选择 创建，再打开新建的 Skill。
注意
创建 Skill 时会自动生成
v1AgentWorks 会同时创建 Skill 和它的第一个版本
v1。新建表单中的SKILL.md内容会保存到v1；即使没有填写内容，仍会生成一个内容为空的v1。v1会成为当时的 latest，因此不需要为了完成首次创建再选择一次 新版本。确认版本列表中已经显示
v1。需要附带其他资源时，在 文件 中上传文件，或通过 新建文件 创建文本文件。
检查
SKILL.md中引用的相对路径能够找到v1中的对应文件，再把这个 Skill 加入测试技能组。
文本文件可以在线编辑和删除；二进制文件不能在线编辑。脚本文件可以作为 Skill 资源保存，但不会因为上传到 Skill 而自动执行、安装依赖或注册为工具。
创建新版本
新版本号由平台自动递增，不能手动填写。例如，当前最高版本是 v1 时，下一次创建、克隆或上传得到的版本就是 v2。新版本会成为 latest；此前的版本仍然保留，但不再带有 latest 标记。
将当前编辑的 SKILL.md 保存为新版本
打开目标 Skill，并在左侧选择要作为参考的版本。
打开 SKILL.md，确认编辑器中是新版本需要保存的完整内容。
选择 新版本。
注意
“新版本”不会复制其他文件
这项操作只使用当前编辑器中的
SKILL.md，不会把当前版本中的脚本、配置、图片或参考文件带入新版本。需要沿用全部文件时，请取消操作，改为选择当前版本的 克隆；平台会把SKILL.md和其他文件一起复制到下一个版本。按需填写新版本信息：
- 描述：说明本次版本修改了什么，便于以后选择和回退。
- 分支：记录该版本对应的代码分支或维护线；这个字段只保存说明，不会连接或同步 Git 分支。
- 创建人：记录本次版本的维护者。
- 标记为 stable：表示团队把这个版本标记为稳定版本。只在完成内容审查和测试后选择。
这些字段均为可选字段。版本号和 latest 状态由平台自动设置。
确认后创建版本。
打开新版本，核对版本号、
SKILL.md和文件列表，再在不会影响现有使用者的环境中验证。
上传 ZIP 作为新版本
准备 ZIP。推荐让
SKILL.md直接位于 ZIP 根目录，并把脚本、配置和参考资料放在相对于它的子目录中：language-textskill-version.zip ├── SKILL.md ├── scripts/ │ └── run.py └── references/ └── checklist.mdZIP 也可以只包含一个顶层目录，并把同样的结构放在该目录中，例如
my-skill/SKILL.md。不要在一份 ZIP 中放入多个 Skill 根目录。在
SKILL.md第一行开始编写 YAML frontmatter。Frontmatter 是两条---之间的版本元数据；后面的 Markdown 才是智能体读取的任务说明。例如：language-markdown--- name: data-validation description: 检查交付数据的结构和内容 --- # 数据检查方法字段 填写要求 nameZIP 导入时必填。使用普通字符串，只能包含 3–32 位英文、数字、连字符（ -）或下划线（_）。上传新版本时，建议与当前 Skill 的名称保持一致。description建议填写一句清楚的用途说明。使用普通字符串；平台不要求必填。 其他字段 只有相应功能文档明确说明时再使用。字段能够保存，不代表 AgentWorks 一定会读取或执行它。 注意
Skill 名称不取自 ZIP 文件名
请继续使用
.zip后缀，方便识别和选择文件。创建新 Skill 时，平台从SKILL.md的name读取名称；上传新版本时，版本会加入当前打开的 Skill。ZIP 文件名和外层目录名都不会改变 Skill 名称。上传前检查 ZIP：
- ZIP 中只保留一个 Skill 根目录。
SKILL.md的大小写完全一致。SKILL.md位于 ZIP 根目录，或唯一顶层目录的根部。SKILL.md使用 UTF-8。- Frontmatter 的起止
---完整。 name和description都使用普通字符串。- 引用的脚本和资料位于同一 Skill 根目录，并使用相对路径。不要在 ZIP 条目中使用绝对路径或
..。
打开目标 Skill，选择 上传新版本，再选择准备好的 ZIP。
确认平台生成了下一个版本号，并检查
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，再选择 克隆。
导入或克隆后，逐个检查 SKILL.md、脚本、配置和附带文件。不要把密钥、个人数据或未经审查的可执行内容加入 Skill。广场提供发现和克隆入口，不表示内容已经通过当前租户的安全或业务审批。
需要在环境间审查或迁移时，可以通过 导出 zip 保存版本文件。导出物可能包含脚本和业务内容，请按组织的软件制品要求保存和传递。
编写便于准确激活的 Skill
智能体先根据 Skill 的名称和描述判断是否需要加载它，再读取运行时解析出的版本。名称和描述应明确区分任务；多个 Skill 的适用范围高度重叠时，智能体可能无法稳定选择预期 Skill。
在 SKILL.md 中写明：
- 这个 Skill 适用于什么任务，以及不适用于什么任务。
- 开始任务前需要具备哪些输入或前提条件。
- 应按什么步骤完成任务。
- 完成后应得到什么结果，以及怎样判断结果正确。
- 需要读取哪些相关文件、文件中包含什么内容，以及何时使用。
- 如果步骤依赖工具或沙箱，应调用什么能力并检查什么执行结果。
加入技能组后，分别使用明确匹配、不匹配以及可能匹配相邻 Skill 的输入进行测试。这样可以同时检查目标 Skill 能否被激活，以及它是否会在无关任务中被误选。
让运行中的智能体使用经过验证的 Skill 版本
把经过验证的版本设为 stable，可以控制运行中的智能体何时开始读取新内容。开始更新前，先确认当前已验证的版本已设为 stable。平台会把新建版本自动标记为 latest；在不影响现有使用者的环境中验证通过后，再把新版本设为 stable，相关智能体实例后续会优先读取它。
理解版本标记怎样影响模板和实例
智能体模板不会保存 stable 或 latest 标记。它引用技能组，技能组让从该模板创建的智能体实例获得相应的 Skill。智能体实例真正读取 Skill 时，运行时优先选择 stable；没有 stable 时，才选择 latest。因此，更改标记不会改写智能体模板或重新创建智能体实例，但可能改变所有相关实例后续读取到的内容。
图中两个智能体实例都来自同一个智能体模板，并通过技能组获得同一个 Skill。版本标记不改变这条配置关系；它们只影响实例在运行时读取这个 Skill 时得到哪个版本。
比较版本操作的影响
| 操作 | 对智能体模板的影响 | 对相关智能体实例后续读取 Skill 的影响 |
|---|---|---|
创建 v2 | 不修改模板 | v2 自动成为 latest；存在 stable 时仍优先读取原 stable，否则读取 v2 |
把 v1 设为 stable | 不修改模板 | 优先读取 v1，即使其他版本是 latest |
把 v2 设为 stable | 不修改模板 | 后续优先读取 v2 |
取消当前 stable | 不修改模板 | 没有其他 stable 时，后续改为读取当前 latest |
注意
stable 由维护者确认
平台不会自动判断某个版本是否已经通过测试。stable 是人工维护的标记；设置后会一直影响运行时选择，直到维护者取消它或把其他版本设为 stable。创建候选版本时，建议先保留平台自动设置的 latest，完成内容检查和运行验证后，再选择 设为 stable。
将新版本投入使用
- 确认当前经过验证的版本已经标记为
stable，避免新建候选版本后立即影响现有实例。 - 选择 新版本，创建候选版本；平台会自动生成版本号并将其标记为
latest。 - 检查候选版本的
SKILL.md和文件列表。 - 在不会影响现有使用者的测试环境中验证触发条件、执行步骤和结果。如果测试环境与生产环境共用同一个 Skill，请使用独立的测试 Skill 副本，避免为了测试而提前改变生产实例所使用的
stable。 - 验证通过后，把候选版本设为
stable。 - 使用目标版本独有的说明或资源执行代表性任务，确认相关智能体实例读取了预期内容。
- 如果需要回退，把此前经过验证的版本重新设为
stable，再执行回归验证。
将 Skill 提供给智能体
准备好 Skill 内容和版本后，把它加入技能组，再让智能体模板关联相应的技能组实例或模板。Skill 内容、技能组交付方式和执行能力是三个不同层次，应分别验证。
将 Skill 加入技能组
打开使用技能组为智能体提供一组 Skill，完成以下选择和操作：
- 选择让多个智能体实例共享一个技能组实例，还是分别生成独立技能组。
- 把目标 Skill 加入相应的技能组实例或模板。
- 把技能组实例或模板添加到智能体模板。
- 创建或更新智能体实例。
让智能体按需激活 Skill
技能组让智能体获得所选 Skill 的名称和描述。处理请求时，智能体可以选择并激活匹配的 Skill；真正读取内容时，运行时再按前述规则解析 stable 或 latest，并读取相应版本的完整 SKILL.md。
一次请求不一定需要 Skill，也不会因为技能组中包含多个 Skill 而依次激活全部 Skill。需要稳定触发目标 Skill 时，请使用只有借助该 Skill 才能正确完成的测试输入。
读取 Skill 引用的资源
如果 SKILL.md 引用脚本、配置、参考资料或其他文件，智能体可以按相对于 Skill 根目录的路径读取运行时解析出的版本中的对应资源：
SKILL.md：提供任务步骤、适用条件、示例和边界。- 相关文本资源：在 Skill 说明需要时读取，作为完成任务的输入。
- 脚本文件：可以读取内容，但不会因此自动执行、安装依赖或注册为工具。
SKILL.md 已经包含完成任务所需信息时，智能体不需要继续读取其他资源。
为 Skill 配置执行能力
Skill 资源读取和工具执行是两条独立路径：
同一个智能体模板同时关联技能组和 沙箱 - 模板 时，所选 Skill 版本以只读方式挂载到沙箱的 /skills 目录；这个沙箱是随智能体实例新建的。直接关联已有 沙箱 - 实例 时，不会增加这项自动挂载。文件已经挂载不表示脚本已经执行。
需要不同 Skill 集合的智能体不能通过复用现有沙箱实例取得各自的 Skill 文件，应使用各自的沙箱。参见选择沙箱模板或实例。
验证 Skill 激活、资源读取和执行结果
创建或更新智能体实例后，分别检查三个层次：
- Skill 激活：用能明确触发目标 Skill 的输入测试，并在 Trace 中确认发生了 Skill 激活。
- 资源读取：测试依赖相关文件时，确认读取了目标版本中的正确相对路径。
- 实际执行：任务需要工具或沙箱时，另外确认工具调用、脚本输出或外部系统结果；Skill 激活本身不能证明操作已经执行。
再用不会触发 Skill 的输入以及可能匹配相邻 Skill 的输入确认边界。使用只存在于目标版本中的短语或样例，可以确认智能体实际解析的 Skill 版本。
注意
Trace 中的 Skill 运行时调用
在当前默认 Skill 提供方下，Trace 中的 Skill 激活和资源读取通常分别显示为 default.activate_skills 和 default.read_skill_resource。它们由 AgentWorks 为已关联技能组的智能体提供，不需要用户另行安装或手动调用，也不提供命令执行能力。
维护 Skill
通过新增版本和调整 stable 完成升级或回退；删除前先确认现有引用和需要保留的制品。
升级或回退 Skill
升级 Skill 时，按将新版本投入使用保留当前 stable，再创建、检查和验证候选版本。测试通过后，把候选版本设为新的 stable；需要回退时，把先前验证的版本重新设为 stable。
同一个 Skill 可能供多个技能组、智能体模板和智能体实例使用。调整 stable 前应确认所有使用者都可以接受这次变化；需要分阶段发布时，使用独立的测试 Skill 副本或测试租户，不要通过共享 Skill 的标记区分不同批次。
删除 Skill 或版本
删除前检查技能组模板、技能组实例、智能体模板和智能体实例的引用：
- 删除
stable或latest版本会改变运行时的版本选择；删除前先为保留版本设置正确标记并完成回归。 - 删除 Skill 会移除其元信息和版本入口，不能自动修复技能组。
先让运行时可以解析到经过验证的替代版本，并在引用该 Skill 的智能体实例中完成回归，再执行删除。需要保留制品时，先通过 导出 zip 保存到团队批准的制品库。