GitHub 在 2026 年 11 月 12 日发布了一份 Agent Skills 实践指南。值得关注的不是又一种提示词写法,而是一个容易被标题掩盖的边界:可以跨代理复用的是工作方法,不是执行环境和权限。文章还特意说明,其独立验证示例做的是代码差异的静态审查,并没有运行测试。GitHub 官方指南
这给团队提出了一个很现实的问题:同一个技能,在开发者电脑上能完成任务,换到云端代理后也能读懂文件,为什么仍然不能算迁移成功?我的判断是,技能复用的交付单位不应只是一个目录,而应包含一份可以检查的执行契约。下面用“为一次发布生成可审阅的变更说明”这个低风险任务,把这件事拆开。示例和验收方案均为本文设计,不是 GitHub 产品默认行为,也不是一次跨客户端实测报告。
能读懂技能,只完成了迁移的第一步
Agent Skills 规范以 SKILL.md 为入口,要求名称和用途描述,也允许配套脚本、参考资料与资源文件。规范中的 compatibility 用于说明环境要求;allowed-tools 仍是实验性字段,不同实现的支持可能不同。不能因为文本里出现某个工具名称,就假设当前宿主已经授予了对应能力。Agent Skills 格式规范
我会把迁移拆成四个独立问题:宿主是否发现技能,代理是否在合适任务上选择它,所需操作是否真的可用,以及结果是否满足原来的验收标准。四者之间没有自动蕴含关系。例如,代理准确引用了发布说明模板,只证明它读过模板;生成了一段漂亮的版本总结,也不证明它读取了正确的提交区间。
这个区别会直接改变排障顺序。若技能从未被加载,继续润色正文毫无帮助,应该检查安装位置和触发描述。若技能已加载却拿不到仓库,应该解决环境接入,而不是给指令加上“务必认真执行”。若输入区间正确、输出却混入旧版本功能,才轮到检查筛选逻辑与模型推理。把所有失败都归因于提示词不够强,会让团队不断增加文字,却始终没有找到出错的层。
GitHub 的产品文档也提醒,技能支持位置随使用入口而异,不能默认个人电脑中的技能会出现在云端会话中。这是具体产品的接入约束,不是模型智力问题。GitHub 技能使用说明
因此,“支持同一种格式”和“产生等价结果”应该分开发布。前者可以用文件检查证明,后者需要任务样本、运行记录与验收结果。团队若对外宣称支持三个客户端,最好同时说明在哪些任务、哪些权限范围和哪些运行环境下验证过,而不是展示三个能打开文件的截图。
先把任务缩到一个可验收的边界
假设我们维护一个带网页界面的订单系统。每次发布要把已经合并的变更整理给业务人员阅读,但不允许代理直接发布公告,也不允许它自行承诺上线时间。技能的输入不是一句“写个更新日志”,而是一个确定的起始提交、结束提交,以及允许读取的仓库。
输出可以是本地 Markdown 文件和一份证据清单。前者供人阅读,后者记录每条变更对应的提交或文件差异。这个设计故意把“写好说明”和“向外发送”分开,因为前者的错误可以在审阅中修正,后者会产生新的沟通成本。是否发送应由发布流程决定,不应藏在一个看似只负责写作的技能里。
边界还包括什么不算成功。没有实际变更时输出“本次无面向用户的变更”,比从重构中杜撰功能更好;只拿到部分差异时应标记不完整,而不是把缺失输入当作空集合;发现数据库迁移文件时可以提醒审阅者核对部署影响,但不能仅凭文件名断言停机时间。不同的不确定性需要不同输出,不能统一用一句“请自行确认”收尾。
这类任务适合技能,是因为材料整理和表达需要一定判断,而输入输出又能被约束。如果目标变成“监听发布事件,等待审批,失败后重试,最后向多个渠道分发”,我会把持久状态与重试交给应用或流水线,技能只承担其中的分析步骤。原因不是技能不够复杂,而是进程中断之后,重新读一遍文字不能恢复已经发生的外部副作用。
契约需要的是可检查字段,不是更多形容词
下面是一份自定义任务清单。它不是 Agent Skills 标准字段,不能直接当成某个客户端的配置导入;它用于说明团队应在技能入口旁保存哪些运行事实。
{
"task": "release-note-draft",
"contractVersion": "1",
"input": {
"baseCommit": "REPLACE_WITH_FULL_COMMIT_ID",
"headCommit": "REPLACE_WITH_FULL_COMMIT_ID"
},
"capabilities": {
"repositoryRead": true,
"network": false,
"externalPublish": false
},
"output": {
"draft": "out/release-notes.md",
"evidence": "out/evidence.json"
},
"completion": {
"requireResolvedCommits": true,
"requireEvidenceForEveryItem": true
}
}
实际运行前必须把占位提交替换成真实值,验证两者可解析,并明确比较的是哪一种差异语义。只比较两个树的最终差异,与收集两个版本之间的提交消息不是一回事:某个功能可能先加入又被撤销,提交历史里有它,最终产品里却没有。这里的契约选择以最终差异支持面向用户的陈述,提交消息只作为理解背景,不单独充当上线证据。
权限字段也不是安全开关。把 externalPublish 写成 false,只表达任务意图;宿主还需要不给发布凭据,或在外部接口上拒绝写入。否则代理仍然处在“被告知不要做,但有能力做”的状态。相反,如果宿主没有联网能力,技能就应接受离线边界,而不是为了补资料自行寻找另一条发送路径。
还有一个常被忽略的问题:同名文件不等于同一份证据。结果清单应该绑定运行时的提交标识、技能版本以及输入清单摘要。审阅者修改了分支后重新运行,旧的验证结果就不能继续给新文件背书。把这些标识放到结果旁边,比在提示词中重复“保证准确”更能减少串版本错误。
独立审查的价值,在于证据不同而不是角色不同
增加一个“审核员代理”并不自动提高可信度。如果它看到的只有作者总结,就会在作者选择的叙事范围内判断;如果它还能读取原始需求、最终差异和检查结果,才有机会发现作者漏掉的事实。更换角色名称没有改变信息来源,隔离作者的自我评价才改变了审查条件。
对发布说明,我会让审查输出三类发现。第一类是无证据断言,例如正文写了“显著提升加载速度”,但变更只有样式调整。第二类是遗漏,例如接口新增了必填字段,却被写成无兼容性影响的小优化。第三类是语义不确定,例如代码出现某个开关,但不知道生产环境是否开启。第三类不应为了得到整齐的通过率而强行归入正确或错误。
这里必须避免把静态审查包装成测试。审查者能从代码推导某条路径可能出错,却不代表它已经启动服务复现;它能看到测试文件,也不代表测试已经通过。结果应分别记录“阅读到了什么”“运行了什么”“观察到了什么”。三者混写,会让一份看似充分的证据清单失去追责价值。
审查也不是越多越好。两位代理可能共享相同的误解,尤其是都把一段过时文档当作现行规则时。与其让三个模型互相投票,我更愿意先增加一个确定性检查:所有发布条目必须引用当前差异中的证据标识,引用不存在就失败。确定性检查不能证明语言解释正确,但能先排除没有材料支撑的输出,把人的注意力留给真正需要判断的地方。
怎样比较两个宿主,而不是比较两次好运气
一次顺利演示最容易掩盖迁移问题。要比较本地代理与云端代理,我会固定技能版本和一组小型仓库样本,每个样本恢复到干净状态,用相同任务输入多次运行。两边可以采用不同模型,但必须记录这个差异,否则看到成功率变化时无法判断是安装方式、工具能力还是模型本身造成的。
样本不应全是干净的功能提交。至少应覆盖功能被回滚、只有内部重构、提交消息与代码不符、变更规模超出可读范围、证据文件缺失,以及仓库文档夹带无关操作要求等情况。最后一种样本测试的不是代理会不会写文章,而是它能否把待分析材料与任务授权区分开。样本仓库不需要包含真实凭据,也不应为了测试而连接生产服务。
记录指标时,先看关键错误,再看完成速度。我会分别计算无证据条目的数量、重大遗漏数量、正确停止的次数、人工修订时间,以及每次验收通过的总成本。成本要把失败重跑和审核算进去:第一次生成很便宜,但需要人工逐句追查,未必比一个较慢但证据清楚的流程划算。
“正确停止”必须单独计数。代理拒绝在缺少提交对象时生成公告,不是普通失败;它遵守了输入契约。但如果输入完整、工具可用却无端停止,也不能算安全成绩。把两者放在同一个失败桶里,会激励团队放宽停止条件,最后得到一个总能产出文字、却不知何时可信的系统。
发布说明的质量评分也需要人审样本。可以让模型辅助标记候选问题,但不要让生成模型同时成为唯一裁判。业务人员关心的是读者能否理解变化,工程人员关心的是有无错误承诺,两种评价都应保留。它们发生冲突时,优先修正错误事实,再改善表达,而不是用一个平均分掩盖重大缺陷。
技能版本变更,也会改变团队的工作方式
技能不是写完就不再维护的说明书。一次看似无害的措辞修改,可能扩大触发范围,使原本只用于准备草稿的技能开始介入故障复盘;一次脚本依赖升级,可能改变输出排序,打破下游的证据匹配。因此,技能版本与宿主版本至少应该能分别追踪,回滚时也应知道退回的是方法还是环境。
我建议把变更分成三类处理。纯表达调整检查旧样本是否仍能理解;决策规则变更增加针对性案例;权限或外部行为变更单独审查,不能夹在模板美化里通过。最后一类尤其重要,因为从“写文件”到“创建拉取请求”,再到“合并和发布”,虽然都可能只多一行指令,影响范围却完全不同。
团队还要决定谁有权修改技能。业务口径归业务负责人确认,执行脚本由工程人员维护,安全边界由宿主控制。把这些责任全压到一个 Markdown 文件的作者身上,会让技能既像需求文档又像权限系统,最后谁都以为另一层已经处理好了。
不值得技能化的工作也要保留。有些一次性探索,问题本身还没定义清楚,过早固定流程会把暂时猜测变成长期惯例。更合理的顺序是先积累几次真实任务,找出稳定步骤和反复出现的错误,再提炼技能。如果每次使用都需要修改一半正文,它可能还不是可复用流程,或者任务边界划得过大。
我会怎样做第一轮落地
对一个已经使用多个编码代理的团队,我会先选发布说明草稿,而不是数据库迁移或生产部署。它能检验仓库读取、资料组织、证据绑定和审查协作,又能把外部影响留在人类确认之后。第一轮只支持一个宿主,建立失败样本;第二轮再迁移到另一个宿主,比较差异,而不是同时铺开后不知道问题来自哪里。
只有当第二个宿主能稳定识别同一类任务、在缺失能力时正确停止、交付同样可检查的证据,并且没有扩大权限,我才会把这项技能称为可迁移。模型生成的句子不必完全一致,关键事实、停止边界和验收依据必须一致。可迁移的是工作质量,而不是文本逐字相同。
本文核对了截至 2026 年 11 月 15 日可读取的上述官方资料,没有安装示例仓库,没有对 Copilot、Claude Code 或其他客户端执行跨宿主对照,也没有测量成功率与费用。文中的任务契约、样本设计和成本口径是可供团队试行的工程方案,不是产品已承诺的能力。
这轮 Skills 热度最值得留下的成果,不是更多共享目录,而是把“代理做完了”变成一句能被检查的话:它依据哪份输入,用了什么能力,在哪个版本上产生什么结果,哪些结论仍需人判断。若这几个问题没有答案,文件可以迁移,信任却不能跟着迁移。
评论
暂无评论。