把 Agent 技能文件写成可审查的工程契约:重复工作如何变成团队资产
一句话回答
Agent 技能文件应作为可审查的工程契约:固化流程、输入输出、验证与失败退出,把工具、权限和项目上下文留给宿主适配层;跨运行时复用需先核对宿主差异,不能假定文件原样可移植。
核心要点 TL;DR
- 技能文件应固化流程、输入输出、验证与失败退出,而不是写死宿主细节。
- 工具、权限和项目上下文仍由宿主决定,换运行时需先做适配与核对。
- 审查重点是输入输出可判定、副作用声明、权限最小化、停止条件和证据。
把 Agent 技能写成可审查资产,关键不是把提示词写长,而是把它当成一份小型工程契约:写清何时使用、输入输出、步骤、工具与权限边界、验证证据和失败退出。事实:GitHub 博客在 2026 年 11 月 12 日的实践指南摘要中把 Agent 技能描述为“把可重复的工程工作捕获到文件中,供团队审查和复用”,同时指出工具、项目上下文和权限仍特定于运行技能的主机。该摘要不等于全文;具体技能字段与加载规则需按宿主核对。
推断:如果目标是团队复用,技能文件应固化稳定流程,把本地路径、密钥和运行时差异外置。否则换一个宿主,文件里的隐含假设就会变成审查盲区。
先拆成三层内容#
建议:把技能文件拆成团队资产、宿主契约和项目实例三层,审查时分别判断。
- 团队资产:适用条件、步骤、判断规则、验收标准、失败分类。这是 review 的重点。
- 宿主契约:工具调用方式、权限申请、可用命令或模型。具体字段取决于宿主,待核实。
- 项目实例:仓库、分支、环境变量名、密钥引用。只写引用,不写值。
事实层面,后两层与宿主相关;因此不要把“我机器上的路径”和“当前会话的权限”当成技能本身。
一个可审查的骨架#
下面是结构演示,不是某运行时的正式规范,也未执行;目的是让审查者逐项判断。
# 技能:生成发布说明
目的:从合并记录生成可审阅的发布说明草稿。
非目标:不创建标签,不发布版本。
适用条件:
- 输入:版本范围、目标分支、排除规则
- 输出:Markdown 草稿与来源链接
步骤:
1. 读取合并记录并按类型分组。
2. 无法分类的条目列入“待确认”。
3. 只生成草稿,不修改仓库文件。
验证:
- 每条说明可追溯到合并记录
- 草稿不含密钥、内部链接或未公开信息
失败与停止:
- 输入范围不明确时停止并提问
- 工具不可用时输出未完成原因
宿主契约:
- 所需权限:只读仓库与合并记录
- 工具映射:由宿主提供,不假设名称
版本与维护:
- 负责人、变更记录、最后审查日期
审查时看什么#
- 输入输出可判定:避免“优化一下”这类无法验收的动词。
- 副作用分开写:读、写、发请求、创建文件分别声明。
- 权限最小化:只申请完成步骤所需的权限;权限模型由宿主决定。
- 有停止条件:缺少输入、工具失败或结果不确定时如何退出。
- 有证据:验证命令、检查清单或人工复核点;不要把预期输出写成实测。
- 可维护:负责人、版本、变更记录和适用范围。
跨宿主复用的边界#
摘要已经指出,工具、项目上下文和权限仍属于宿主。因此“Build once, run on any agent”不宜理解成文件完全不变。更稳妥的做法是:流程与验收标准写成稳定资产,工具名、路径、权限声明做成宿主适配层;换运行时先核对加载规则、权限模型和工具能力。没有在多个宿主实际运行过,就不能声称可移植性已经验证。
结论:可审查写法让技能像代码一样被 review:边界清楚、证据可查、失败可退出。它不保证每个宿主行为一致,但能减少团队复用时的隐性假设。
参考来源
以上为本文写作时的参考资料,引用观点以原文为准。