智能体技能的文件化复用:哪些能跨运行时搬走,哪些必须留在宿主
文件化技能可以把意图、步骤和评审材料固定下来并跨宿主复用,但工具调用、项目上下文和权限仍由承载它的运行时决定。真正可移植的做法是把技能拆成纯文本正文、显式前置条件和宿主适配层,并用同一份技能在两个宿主上的实际行为来验证,而不是只比较文件内容。
- 可复用的是“做什么、按什么顺序做、怎么审”,不可复用是工具、权限和项目上下文。
- 判断可移植性要看同一份技能在两个宿主上的实际行为差异,文件相同不等于行为相同。
能复用,但只复用一半。据 GitHub 博客的介绍,智能体技能(agent skills)把可重复的工程工作写进文件,团队可以审阅和复用;而工具、项目上下文和权限仍然属于运行它的宿主(GitHub Blog)。换句话说,文件解决的是“怎么把做法写下来并被评审”,不解决“换一个运行时还能照原样执行”。
能搬走的部分#
- 意图与边界:这个技能要解决什么问题、什么情况不该用。
- 步骤顺序:先收集什么信息、再做什么判断、最后产出什么形状的结果。
- 评审材料:为什么这么写、哪些坑已经踩过。这是文件化相比聊天记录最大的价值——它能进代码评审。
- 版本与历史:改动可追溯,回滚有依据。
这些内容的共同点是纯文本,不依赖具体工具名、路径或凭据。它们在任何能读取文件的宿主上含义都不变。
搬不走的四类东西#
| 类别 | 例子 | 为什么绑定宿主 |
|---|---|---|
| 工具与接口 | 文件读写、终端、检索、子智能体 | 工具名、参数、返回结构由宿主的工具集决定,换个运行时可能不存在 |
| 权限与审批 | 能否写文件、能否发起网络请求、是否需要人工确认 | 权限模型属于宿主策略,不写在技能文件里 |
| 项目上下文 | 目录结构、构建命令、代码规范、依赖版本 | 同一份技能在不同仓库里要读的是不同东西 |
| 执行预算 | 步数、超时、并发 | 由运行时限制,技能正文无法保证 |
这四类中任意一类在目标宿主上缺失,技能就会“跑得起来但结果不对”,这比直接报错更难发现。
拆法:正文、前置条件、适配层#
让技能尽量可移植,做法不是把工具调用写得更通用,而是把不可移植的部分显式隔离出来。
# 示意结构,未在具体宿主上执行
skill/
SKILL.md # 意图、步骤、验收标准(纯文本,尽量不含工具名)
requirements.md # 前置条件:需要哪些能力,缺了怎么办
adapters/
host-a.md # 该宿主上的工具映射与差异说明
host-b.md
技能正文只描述动作意图,例如“读取目标目录下的配置并校验必填字段”,而不是写死某个工具调用。适配层负责把意图翻译成具体工具,并记录差异。前置条件用来提前声明失败边界:宿主没有写权限时,技能应该明确停下并说明缺少什么,而不是尝试绕过。
含副作用的动作要特别标注。只读的分析步骤通常能跨宿主迁移,而提交、部署、删除这类操作应在正文里要求人工确认,把审批交给宿主而不是写在技能里。
怎么验证真的可移植#
- 选两个宿主,能力集不要完全重合,差异才有意义。
- 用同一份技能正文,同一组输入,分别运行。
- 比对三件事:产出的结构是否一致、中途读取的信息是否一致、失败时的停止点是否一致。
- 把差异写回适配层或前置条件,而不是改正文去迁就某一个宿主。
只比较文件内容不算验证。文件相同、行为不同是常态,因为差异来自工具和权限。
什么时候不值得追求复用#
如果技能深度依赖某一宿主的专有能力(例如特定的子智能体编排或本地终端),硬拆成通用正文反而会丢掉关键步骤,并制造“看起来通用、实际只有一处能用”的假象。这种情况下更诚实的做法是把它标记为单宿主技能,在文件里写明适用范围,等第二个宿主确实需要时再抽适配层。
跨运行时复用的合理目标不是零差异,而是差异可见、可控、可评审。能做到这一点,文件化技能包的收益才站得住。
参考来源
以上为本文写作时的参考资料,引用观点以原文为准。