跳转到内容
Agentic Engineering Fieldbook

Agent Skill 格式与扩展机制

观察日期与维护状态

Section titled “观察日期与维护状态”

观察日期：2026-07-23。

适用范围：Agent Skills specification、OpenAI Tools and Skills 文档，以及 Claude Skills 产品文档。

维护状态：持续维护的领域笔记。当 Agent Skills specification 改变包要求，主要产品改变 Skill 打包或加载行为，或跨多个宿主环境的兼容性主张变得可测试时，应重新审阅。

当前观察

Section titled “当前观察”

Skill 格式正在成为一种常见方式，用来为智能体系统打包可复用任务知识。正在形成的形态很简单：一个具名包包含一个入口文档，例如 SKILL.md，并可附带示例、参考材料、脚本、模板或资产等支持文件。宿主环境可以决定何时把这个包加载进上下文，或开放其中的支持资源。

这种打包方式有价值，因为它给团队提供了一个可审查的产物。与其把任务说明散落在提示词、入门备注、notebook 和脚本里，Skill 可以把任务意图、所需知识、约束和示例放在一个有版本的地方。它也自然形成了测试边界：加载这个 Skill，运行这些代表性任务，检查这些追踪记录，并验证这些输出。

风险在于把它看得过重。Skill 不是执行者，不是权限授予，不是沙盒，不是依赖锁文件，也不能保证模型会正确使用说明。它只是打包后的上下文和可选支持材料。宿主环境和周围系统仍然决定哪些内容进入模型上下文、哪些工具存在、哪些脚本可以运行、哪些外部影响被允许，以及哪些输出被接受。

持久工程含义

Section titled “持久工程含义”

把 Skill 当作会影响系统行为、也带有供应链风险的内容来管理。

内容审查时，要看 Skill 是否说明了任务边界、预期输入、预期输出、来源限制、假设、失败条件和升级处理路径。一个写着“总是使用这个供应商”或“忽略系统警告”的 Skill 不只是普通文字；被加载后，它可能改变运行时行为。

在安全审查中，要区分说明文件和可执行文件。SKILL.md 可以改变模型行为，而脚本可以改变环境。两者都需要审查，但控制方式不同。脚本可能需要签名、依赖扫描、沙盒、网络限制、文件系统限制和审计记录。参考文件可能需要新鲜度规则和来源与流转记录。

发布审查时，要像管理提示词和工具 schema 一样认真地版本管理 Skill。一个小小的示例改动可能改变模型行为。一份过期参考材料可能保留已经废弃的 API。包重命名可能破坏路由。宿主环境升级也可能改变 Skill 被加载的时机或方式。

不要这样理解

Section titled “不要这样理解”

不要把 SKILL.md 当作通用智能体架构原语。它是一种用于打包任务知识的格式约定。真正持久的架构问题仍然是：增加了什么能力，授予了什么权限，哪个执行边界负责强制执行，什么证据能证明结果。

不要从相似名称推断兼容性。两个产品都可能支持“Skills”，但它们在元数据、触发行为、允许的文件、执行权限、依赖处理、用户控制和分发模型上可能不同。

不要因为一个 Skill 没有编译代码，就认为它是安全的。说明仍然可能鼓励不安全的工具使用，通过参数外泄数据，压低不确定性，或诱导模型绕过复核。

操作清单

Section titled “操作清单”
  • 记录 Skill 名称、版本、来源、负责人、许可证、预期宿主环境和支持的任务边界。
  • 审查 SKILL.md 中的任务范围、假设、禁止行为、来源新鲜度、权限主张和升级处理说明。
  • 将脚本和依赖与说明文字分开审查；执行前应用沙盒和供应链控制。
  • 分别在加载和不加载该 Skill 的情况下测试，确认它改善了目标结果，而不是只改变表达风格。
  • 当参考材料和示例描述 API、策略、价格、产品或标准时，保留日期。
  • 避免在 Skill 包中嵌入密钥、凭证、私有数据或过宽的工具权限。
  • 定义退役行为：当一个 Skill 被替代、过期、不安全或无人负责时，停止加载它，并为受影响工作保留迁移路径。
  • 将跨宿主环境的可移植性视为需要测试的主张，而不是从包名就能推断出的属性。

参考文献及其使用方式

Section titled “参考文献及其使用方式”