Wiki Notes

Appearance

04C. Skill 任务封装与复用 ​

版本：v1.2

最后更新：2026-07-09

适用对象：希望把 Prompt、上下文、工具暴露和执行策略封成可复用任务入口的产品、平台、应用与 Agent 工程同学

1. 为什么 Skill 也要单独讲 ​

很多团队在做 Agent 复用时会卡在一个很尴尬的中间层：

  • Prompt 只有一段文字，复用不了完整场景
  • Tool 只是最小能力接口，承载不了任务策略
  • Workflow 过重，不适合所有场景都先建状态机

这时就会自然出现一个平台层概念：

  • Skill = 把某类任务需要的指令、上下文、允许工具和执行策略打包成可复用入口

所以 Skill 解决的不是“系统能不能做某件事”，而是“某类任务应该如何稳定地使用这些能力”。

2. Skill 先要和 MCP、Prompt、Tool 分开 ​

这是最容易混的一组概念。

2.1 Skill 不是 Tool ​

Tool 回答的是：

  • 能执行什么动作

Skill 回答的是：

  • 在某类任务里该怎么组织这些动作

2.2 Skill 不是 MCP 原语 ​

MCP 官方架构强调的是：

  • tools
  • resources
  • prompts

并没有把 Skill 定义成协议层标准对象。

所以这里的 Skill 更适合被理解为：

  • 平台层或应用层的复用封装概念

2.3 Skill 也不等于一段 Prompt ​

一段系统提示词通常不够承载：

  • 上下文模板
  • 允许工具集合
  • 审批规则
  • 输出契约
  • 失败后的处理约定

如果只剩一段 Prompt，通常还不够称为一个完整 Skill。

2.4 Skill 更像“任务能力包”，不是“提示词片段” ​

一个成熟 Skill 通常要同时回答：

  1. 什么时候该用它
  2. 它要解决什么任务目标
  3. 启动时需要注入哪些上下文
  4. 它允许看到哪些工具
  5. 它的执行边界和审批边界是什么
  6. 最终输出应该长成什么样

也就是说，Skill 更接近：

  • capability pack
  • playbook
  • workflow preset
  • task template

而不只是“给模型多喂一点说明文字”。

3. OpenAI 官方 Skill 形态到底是什么 ​

OpenAI 当前官方 Skills 指南给出的 Skill 形态非常明确：

  • Skill = versioned bundle of files + SKILL.md manifest

这条定义特别值得拿来做工程基线，因为它天然带来了三件事：

  • Skill 不再只是 prompt 文本，而是文件包
  • Skill 天然支持版本化
  • Skill 可以同时携带说明、脚本、模板和辅助资源

3.1 SKILL.md 是入口，不是可选配件 ​

OpenAI 当前官方文档强调，一个 skill bundle 的关键入口就是 SKILL.md。

它通常承担两层职责：

  • 前置 front matter
  • 核心 instructions

文档示例里最小 front matter 至少包含：

  • name
  • description

这意味着 Skill 不只是“模型能读的一段说明”，还是：

  • 宿主运行时可发现、可挂载、可版本化的能力对象

3.2 Skill 是文件包，不是纯文本配置 ​

Skill bundle 里除了 SKILL.md，还可以包含：

  • 脚本
  • 模板
  • 示例数据
  • 约束说明
  • 任务参考材料

这点非常关键，因为很多团队做复用时最痛的地方恰恰是：

  • Prompt 在文档里
  • 脚本在仓库另一个目录
  • 样例在 wiki
  • 执行规则在某个页面配置里

Skill 的价值就是把这些东西收成一个版本化能力包。

3.3 Skill 和 open Agent Skills standard 的关系 ​

OpenAI 当前官方文档明确写到：

  • Skills are compatible with the open Agent Skills standard

它带来的现实意义是：

  • Skill 不是某个团队私造的神秘黑盒
  • 它更适合被当成一个逐步标准化的复用对象

对于团队内部治理来说，这意味着 Skill 最好也具备：

  • 命名规范
  • owner
  • 版本号
  • 更新说明
  • 回归样例

3.4 用同一个例子，把 Skill 单独看清 ​

继续拿“事故分诊”举例：

  • Tool 是 read_recent_alerts、search_runbook、create_incident_ticket
  • MCP 是把告警系统、文档和工单能力按统一协议接出去
  • Skill 则是“事故分诊”这个可复用任务入口

这个 Skill 真正关心的通常不是某个接口字段，而是：

  • 什么情况下应该启动事故分诊
  • 启动时要带哪些上下文
  • 默认只允许哪些只读工具
  • 什么时候必须升级到人工审批
  • 最终要输出什么格式的分诊结论

也就是说，Skill 的价值在于把“场景经验”收成一个包，而不是重新定义协议，也不是取代单个 Tool 契约。

4. 一个成熟 Skill 通常包含什么 ​

从工程视角看，一个 Skill 至少会包含下面这些部分：

组成解决的问题
instructions这个 skill 什么时候该用、目标是什么
context template启动时注入哪些上下文、哪些资料、哪些约束
allowed tools这个场景允许看到哪些能力
execution policy是否允许写操作、是否允许并行、是否需要审批
output contract返回摘要、产物或结构化结果应该长什么样
eval checklist怎样判断这个 skill 真正可用

一句话说：

  • Skill = instructions + context + allowed tools + policy + output contract

4.1 Skill 最好显式写“何时使用”和“何时不要使用” ​

如果 Skill 只写“你可以做什么”，不写“什么时候该触发”，模型往往会：

  • 不知道该不该用
  • 过早触发
  • 在相近 skill 之间误选

更稳的写法通常会同时说明：

  • 适用任务
  • 非适用任务
  • 需要哪些前置证据
  • 哪些情况必须交给别的 skill 或别的 workflow

4.2 Skill 最好自带最小 output contract ​

很多团队把 Skill 当成“执行过程提示包”，但忘了它最终还要交付结果。

如果没有 output contract，最后经常会变成：

  • 看起来写得挺好
  • 但下游系统消费不了
  • 也很难做稳定评测

所以至少要明确：

  • 返回给人看的摘要长什么样
  • 返回给系统的结构化对象长什么样
  • 失败时怎么返回

4.3 一个最小 Skill bundle 可以长这样 ​

如果你想把 Skill 真正做成团队资产，一个很小但完整的 bundle 通常至少像这样：

text
incident-triage/
  SKILL.md
  checklists/
    escalation-rules.md
  templates/
    triage-summary.md
  examples/
    successful-case.json

其中 SKILL.md 更像这个 bundle 的入口：

md
---
name: incident-triage
description: 用于线上事故的快速分诊、证据归纳和升级建议。
---

Use this skill when the user is diagnosing a production incident.
Prefer read-only tools first. Do not create or update tickets until evidence is sufficient.
Return a short triage summary, suspected root cause, missing evidence, and whether escalation is required.

这类结构的关键价值是：

  • 指令、模板、样例和检查项不再散在多个目录
  • 版本升级时更容易回归
  • 新人接手时更容易看懂“这个任务到底怎么做”

5. Skill 最重要的价值是什么 ​

5.1 把“场景经验”从 prompt 文本里抽出来 ​

如果没有 Skill，很多经验会散在：

  • 某段系统提示词
  • 某个页面配置
  • 某个项目私有脚本
  • 某个同学口头经验

Skill 的价值就是把这类经验收敛成一个明确入口。

5.2 把工具暴露范围缩小到任务所需的最小面 ​

不是所有任务都该看到同一批工具。

例如“事故分诊 Skill”和“日报整理 Skill”看到的工具面就不该一样。

Skill 非常适合承接：

  • 最小工具面暴露
  • 最小上下文暴露
  • 任务级输出约束

5.3 让复用对象从“单个提示词”升级成“任务能力包” ​

当团队说“这个场景以后还能复用”，真正应该复用的通常不是一句 Prompt，而是一整套任务约束。

5.4 让任务经验变成可版本化资产 ​

Skill 一旦成了 bundle，就天然适合做：

  • 版本对比
  • 默认版本切换
  • 回归集绑定
  • 发布窗口治理

这会比“直接改老 prompt 文本”稳定很多。

6. 在 OpenAI 运行时里，Skill 是怎么被模型看到的 ​

这部分非常关键，因为它决定了 Skill 到底是“静态配置”，还是“运行时可发现能力”。

6.1 一旦 skill 被挂载，模型先看到的是元数据 ​

OpenAI 当前 Skills 官方文档说明：

  • 当 skill 可用于 tool 时，平台会把每个 skill 的 name、description、path 加进 user prompt context

这意味着模型一开始先看到的是：

  • 这个 skill 叫什么
  • 它大概是做什么的
  • 如果要用它，该去哪里读完整说明

这点非常像“任务入口目录”，而不是直接把所有 skill 正文预塞给模型。

6.2 模型决定是否触发 skill，触发后再去读 SKILL.md ​

官方文档还明确写到：

  • 模型会基于这些元数据决定是否调用某个 skill
  • 如果模型调用某个 skill，它会使用 path 去读取 SKILL.md 的完整 Markdown 说明

这件事的工程含义很大：

  • 不是所有 skill 正文都会无脑进入上下文
  • skill 入口描述质量会直接影响触发正确率
  • name 和 description 其实就是 skill 发现层的关键接口

6.3 想要更稳定的行为，最好显式点名要用哪个 skill ​

OpenAI 当前文档明确建议：

  • 如果你想要更 deterministic 的行为，可以在提示中显式 instruct model to use the <skill name> skill

这意味着团队可以把 skill 使用策略分成两层：

  • 自动发现：模型自己判断何时触发
  • 显式指定：某类任务强制或优先用某个 skill

对于高价值、高风险或高成本任务，后者通常更稳。

6.4 Skill 内容在 OpenAI 里属于 user prompt input，不是 system prompt input ​

这是 Skills 指南里最容易被忽略、但工程上非常重要的一点：

  • Skill instructions are user prompt input, not system prompt input

也就是说，skill 内容虽然能强烈影响：

  • planning
  • tool usage
  • command execution

但它在优先级上不是“系统层绝对规则”，而是更接近：

  • 被挂载进上下文的用户侧任务材料

这对系统设计有两个直接影响：

  1. 不能把最高优先级安全策略只放在 skill 里
  2. Skill 更适合承接任务经验，而不是唯一的系统安全边界

7. Hosted shell、local shell 和 Skill 挂载方式不一样 ​

7.1 Hosted shell 主要靠 skill_reference ​

OpenAI 当前官方文档里，hosted shell 的典型方式是：

  • 在 tools[].environment.skills 里挂 skill_reference

这意味着运行时会去挂载：

  • 指定 skill_id
  • 指定版本，或默认版本

这更适合：

  • 平台托管环境
  • 多版本治理
  • 统一运营和灰度切换

7.2 Local shell 不支持同样的 skill_reference 挂载格式 ​

官方文档专门强调：

  • local shell 和 hosted shell 不接受同样的 skill attachment formats

local shell 的做法更像：

  • 由你控制运行时
  • 直接提供本地 skill 文件路径

这带来的工程差异是：

  • hosted 更像平台级资产管理
  • local 更像项目级或开发时装配

7.3 这不是小差异，而是两种完全不同的治理模式 ​

比较实用的理解是：

模式更像什么更适合什么
Hosted shell平台托管能力市场多版本、复用、统一管控
Local shell项目内挂载能力包调试、私有资产、本地工程环境

如果团队不分这两种模式，后面会在：

  • 版本管理
  • 权限边界
  • 发布流程
  • 本地调试一致性

这些地方踩坑。

8. Skill 和 Workflow 有什么区别 ​

Skill 不一定等于 Workflow。

更实用的区分通常是：

  • Skill 更偏任务入口和能力封装
  • Workflow 更偏状态推进和执行编排

如果一个场景主要需要：

  • 固定入口
  • 固定上下文模板
  • 固定工具面
  • 固定输出要求

那 Skill 往往就够了。

如果一个场景已经需要：

  • 多阶段状态推进
  • 审批恢复
  • 补偿回滚
  • 长任务恢复

那它更像 Workflow 或 Skill + Workflow 的组合。

8.1 Tool、Skill、Workflow 可以理解成三层复用粒度 ​

一个很实用的心智模型是：

  • Tool：最小动作
  • Skill：任务入口
  • Workflow：状态推进

如果一个团队直接跳过中间这层 Skill，经常会出现两种极端：

  • 不是所有经验都堆进 prompt
  • 就是所有事情都先上状态机

前者太散，后者太重。

9. Skill 最常见的错误封装方式 ​

9.1 只写一段长 Prompt，就叫 Skill ​

这通常会缺：

  • 工具面约束
  • 上下文模板
  • 风险策略
  • 输出契约

9.2 一个 Skill 暴露全部工具 ​

这样做最常见的问题是：

  • 工具面过大
  • 成本过高
  • 高风险能力过早可见
  • 评测口径混乱

9.3 Skill 不带 output contract ​

没有输出契约，最后往往变成：

  • 看起来写得挺好
  • 但下游系统消费不了
  • 也很难做稳定评测

9.4 Skill 不带评测口径 ​

如果你说这是“可复用能力”，就必须回答：

  • 什么任务适合用它
  • 什么结果算成功
  • 什么失败要回归测试

9.5 把 Skill 当成“最高优先级安全层” ​

由于 OpenAI 当前官方文档明确说明 skill 内容属于 user prompt input，所以不要把核心安全边界只押在 skill 上。

更稳的分层通常是：

  • system / platform policy 管系统级硬边界
  • skill 管任务级经验和操作惯例
  • tool / approval 管高风险动作执行边界

10. OpenAI Skills guide 对我们有什么启发 ​

OpenAI 当前的 Skills 指南把 Skill 看成一种可复用能力封装方式，重点强调的方向包括：

  • 用可发现、可挂载的说明材料补足模型在特定任务上的表现
  • 让模型在合适时机调用对应技能
  • 把领域经验从单轮提示词里抽成可复用知识包
  • 用 versioned bundle 的方式管理技能资产

把这个思路放到 Agent 工程里，最重要的启发是：

  • Skill 更适合承接“任务级经验复用”
  • Tool 更适合承接“最小动作接口”
  • MCP 更适合承接“标准化能力暴露”

这三层不要再混成一句“我们接了很多能力”。

10.1 Curated skills、inline skills 和自建 skill 适合不同阶段 ​

OpenAI 当前官方文档里，skills 至少有三种实操形态：

  • curated skills
  • inline skills
  • 自建上传 skill

它们各自更像：

形态更适合什么
Curated skill快速使用 OpenAI 维护的第一方 skill
Inline skill临时、轻量、嵌入式分发
Hosted uploaded skill正式资产管理、版本治理、复用

这意味着团队不一定要一开始就做最重的发布流程，但最好清楚自己现在在哪个阶段。

10.2 版本指针治理比“覆盖旧说明”稳得多 ​

OpenAI 官方文档里明确有：

  • default_version
  • latest_version
  • skill_reference.version

这其实提供了一个非常成熟的治理思路：

  • 运行时默认用哪个版本
  • 最新上传的是哪个版本
  • 某个任务要不要强锁特定版本

这比“直接改老 prompt，再希望线上都自动一致”稳得多。

11. 一个容易落地的 Skill 模板 ​

下面是一种很实用的心智模型：

11.1 任务目标 ​

  • 这个 Skill 帮谁完成什么任务

11.2 输入和上下文 ​

  • 启动时需要什么用户输入
  • 允许带什么证据
  • 哪些上下文一定要注入

11.3 允许工具 ​

  • 哪些工具必须可见
  • 哪些高风险工具默认不可见
  • 哪些工具只能在审批后解锁

11.4 执行策略 ​

  • 允许并行吗
  • 允许写操作吗
  • 需要人工确认吗
  • 遇到哪类错误必须停下

11.5 输出契约 ​

  • 最终返回自然语言说明、结构化摘要，还是可落库对象

11.6 评测清单 ​

  • 成功样例
  • 失败样例
  • 高风险样例
  • 回归样例

11.7 版本与 owner ​

  • 谁维护它
  • 默认版本是谁
  • 哪类改动必须升版本
  • 旧版本保留多久

12. Skill 特别适合什么场景 ​

下面这些场景通常很适合封 Skill：

  • 事故分诊
  • 变更巡检
  • 交付物生成
  • 面试题整理
  • 文档归类与摘要
  • 多步检索但状态还不算复杂的任务

共同特征通常是：

  • 有稳定目标
  • 有稳定上下文模板
  • 有稳定工具集合
  • 需要复用场景经验

12.1 不太适合 Skill 单独解决的场景 ​

下面这些情况更可能需要 workflow、guardrail 或系统级治理配合：

  • 高风险写操作必须多阶段审批
  • 长任务需要 pause / resume / compensation
  • 多 agent 之间要做明确 ownership handoff
  • 系统级安全边界必须高优先级强约束

这时 Skill 仍然有价值，但它不该单独扛完整方案。

13. Skill 的安全边界不能省 ​

OpenAI 当前官方 Skills 文档的安全部分其实写得非常直接：

  • Skills introduce security risks such as prompt injection-driven data exfiltration
  • Skill content can influence planning, tool usage, and command execution

这意味着 Skill 应该被当成：

  • 具备执行影响力的特权说明与代码包

而不是：

  • 单纯无害的帮助文档

13.1 不要把开放技能目录直接暴露给终端用户 ​

OpenAI 当前官方文档明确建议：

  • 不要设计成让终端用户自由浏览、选择、挂载任意 open skills repository

因为这会显著增加：

  • prompt injection
  • policy bypass
  • data exfiltration
  • destructive automation

13.2 Skill 应该由开发者集成，再通过有边界的产品体验暴露 ​

官方建议的更稳做法本质上是：

  • 技能由开发者审查和集成
  • 最终用户只通过受限场景体验它

翻译成工程语言就是：

  • 先做 skill 审查
  • 再做任务映射
  • 再决定用户能通过哪个入口触达

13.3 高风险动作仍然要显式审批 ​

即便某个 skill 本身已经写得很完整，只要它能触发：

  • 写操作
  • 外部副作用
  • 高影响系统变更

仍然应该保留显式 approval，而不是把风险藏在 skill 的说明文字里。

14. Skill 的落地检查清单 ​

  • 是否已经把 Skill 和 Tool、MCP、Workflow 区分清楚
  • 是否写清了任务目标、输入和适用边界
  • 是否限制了 allowed tools，而不是默认全量暴露
  • 是否包含执行策略、风险边界和审批要求
  • 是否定义了输出契约和评测口径
  • 是否定义了 owner、版本和默认版本切换策略
  • 是否区分了 hosted shell 与 local shell 的挂载差异
  • 是否明确了 skill 触发依赖 name、description 和 SKILL.md
  • 是否意识到 skill 内容在 OpenAI 里属于 user prompt input
  • 是否对 prompt injection、数据外泄和高风险动作保留了额外控制

15. 推荐联读 ​

16. 参考资料 ​