跳转到内容
Agentic Engineering Fieldbook

Agent Skill 格式与扩展机制

观察日期与维护状态

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

观察日期：2026-09-12。

适用范围：Agent Skills specification、OpenAI Tools and Skills 文档、Claude Skills 产品文档，以及 OpenAI 关于 GPT-6 Astra 的当前 Skill 与提示词报告。

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

当前观察

Section titled “当前观察”

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

Skill 描述本身也参与加载决策。应把它视为路由元数据：说明 Skill 处理哪类任务，并在有助于区分相邻任务时说明它不处理什么。宿主环境呈现大量 Skill 时，过宽的描述可能导致误触发；过短的描述又可能让正确的 Skill 无法被发现。这些是需要测量的当前宿主和模型行为，不是通用的长度规则。

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

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

持久工程含义

Section titled “持久工程含义”

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

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

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

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

把入口设计成路由器。根目录的 SKILL.md 应聚焦任务边界、输入、输出、安全条件，以及指向详细参考材料或脚本的链接。把大多数任务不需要的内容延后加载，但要分别测试两个阶段：代表性请求是否发现了该 Skill，以及加载细节后结果是否改善。还要记录触发遗漏或延后文件不可用时的恢复路径。

如果跨模型共享 Skill 已经有效，就优先共享。只有在出现经过测量的行为缺口时，才创建模型专用变体，并用实际使用它的模型、宿主和推理设置对变体进行版本管理与评估。较新的模型可能需要更少脚手架，但这不意味着可以凭假设安全地删除或保留说明。

仓库指导也应采用同样的风险分级方式：让任务指向完成当前决策所需的文档，而不是要求每个低风险编辑都读取完整仓库地图。高后果变更、负责人不清晰的工作，以及安全和发布工作，仍然适合扩大阅读范围。

不要这样理解

Section titled “不要这样理解”

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

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

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

不要把关于 GPT-6 Astra 的当前报告推广成关于 Skill 长度、仓库阅读、模型持续执行能力或测试的通用规则。较旧或较小的模型，以及高后果任务，可能需要更明确的流程。模型对齐不是安全边界；权限、校验和效果控制仍必须由宿主环境强制执行。

操作清单

Section titled “操作清单”
  • 记录 Skill 名称、版本、来源、负责人、许可证、预期宿主环境和支持的任务边界。
  • 保持描述简洁、针对具体任务且有区分度；在能避免误触发时写出排除范围。
  • 审查 SKILL.md 中的任务范围、假设、禁止行为、来源新鲜度、权限主张和升级处理说明。
  • 将根文档做成最小路由器，提供可发现的延后参考材料和脚本指针；定义发现或加载失败时的处理方式。
  • 将脚本和依赖与说明文字分开审查；执行前应用沙盒和供应链控制。
  • 分别测试 Skill 的发现、误触发和加载后使用，并保留每次结果对应的模型与宿主记录。
  • 模型升级后审查共享指导与模型专用指导，包括继承的说明、示例和工具是否仍值得其成本。
  • 明确完成、检查、修复和安全本地测试的边界，但不得因此授权生产效果或绕过审批。
  • 当参考材料和示例描述 API、策略、价格、产品或标准时，保留日期。
  • 避免在 Skill 包中嵌入密钥、凭证、私有数据或过宽的工具权限。
  • 定义退役行为：当一个 Skill 被替代、过期、不安全或无人负责时，停止加载它，并为受影响工作保留迁移路径。
  • 将跨宿主环境的可移植性视为需要测试的主张，而不是从包名就能推断出的属性。

参考文献及其使用方式

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