智能体技能跨宿主复用:文件里该放什么、不该放什么
一句话回答
技能文件应固化换宿主后仍成立的工程意图——目标、步骤、判定与失败处理;工具调用、项目上下文、权限与凭据属于宿主层,应外置或参数化。GitHub 博文摘要只支持这一条分层,具体宿主字段规范与兼容矩阵待核实。
把智能体技能(agent skill)写进文件,目的是让一段可重复的工程工作能被团队审阅、复用。GitHub 博文摘要给出的分层很直接:技能文件承载可复用的工作本身,而工具、项目上下文和权限仍属于运行它的宿主(GitHub Blog,2026-11-12)。由此可以推出一条简单判据:写之前先问,换一个宿主,这句话还成立吗?成立就留在文件里,不成立就该外置。
三类内容,三个位置#
下表是本人在上述分层之上做的整理,属于推断与建议,不是来源原文。表中“随谁变”一列是判断依据,不是兼容性结论。
| 内容 | 随谁变 | 建议位置 | 理由 |
|---|---|---|---|
| 目标、完成标准、不做的事 | 基本不变 | 技能文件 | 换宿主后语义相同,是复用的核心 |
| 步骤顺序、分支条件、失败处理 | 基本不变 | 技能文件 | 描述的是工作方法,不是执行手段 |
| 输入输出形态约定 | 多半不变 | 技能文件,可变部分参数化 | 格式约定通常可移植 |
| 具体工具名与调用参数 | 宿主 | 宿主配置或技能外置 | 摘要明确指出工具属于宿主 |
| 仓库路径、包名、环境变量 | 项目 | 项目级配置 | 摘要把项目上下文归到宿主一侧 |
| 权限声明、凭据 | 宿主/环境 | 宿主权限体系与密钥管理 | 摘要明确权限属于宿主 |
| 模型名、采样参数 | 运行时 | 运行参数 | 推断;各宿主是否支持待核实 |
该写进文件的部分#
- 目标与边界:这段技能解决什么问题,明确不处理什么。审阅者先看这个。
- 前置条件:需要调用方提供哪些输入,缺了怎么办。
- 步骤与判定:按什么顺序做,在什么条件下跳过或停止。
- 失败与退出:拿不到数据、结果不确定时,是继续、降级还是终止。
- 验收清单:什么算完成,最好能被人逐条核对。
- 示例:示例输入与期望输出,并注明是示例而非真实数据。
这些内容的共同点是:它们描述“做什么、按什么标准算做完”,不描述“用哪个接口做完”。
不该写死、该外置的部分#
- 工具绑定:把“先调用 X 再调用 Y”写进技能,等于把技能锁在某个宿主上。
- 绝对路径与仓库结构假设:换项目就失效。
- 凭据与权限申请:摘要把权限划归宿主;凭据更不应出现在可提交的文件里。
- 宿主专有字段:不同宿主对技能文件的字段名与支持程度并不一致,具体规范需查对应宿主文档,本次材料未提供,待核实。
一个人读得懂的骨架示例#
下面是为说明分层而写的演示结构,未在任何宿主上执行,字段名仅作示意,不代表任一宿主的实际格式。
# 演示骨架,未执行
name: 变更说明生成
goal: 从一组提交生成面向使用者的变更说明
not_in_scope: 不判断代码质量,不修改仓库
inputs:
- 提交范围(由调用方传入,不写死分支名)
steps:
1. 读取提交信息与改动文件
2. 按 新增 / 修复 / 不兼容变更 分类
3. 输出 Markdown 列表
done_when:
- 每条都指向具体改动
- 无使用者可见变更时明确写出
on_missing:
- 提交范围为空:停止并说明原因
# 此处不声明:用哪个工具读提交、凭据、仓库绝对路径
复用前的最小检查#
- 在技能文件里搜索宿主专有名词、绝对路径和凭据痕迹,逐条判断能否换成参数。
- 换一个宿主,只补宿主侧配置,看技能文件是否需要改动;需要改,说明可移植的部分还没抽干净。
- 用一个最小任务跑通,确认失败路径的说明在实际执行中说得通。
以上是方法建议。本文没有做跨宿主实测,因此不对兼容性、成功率或性能给出任何数字。
材料支持到哪一步#
可确认的只有摘要那句话的分层:工作可文件化复用,工具、项目上下文与权限留在宿主。摘要没有给出字段规范、支持矩阵和版本信息,也没有说明不同宿主间的迁移成本,这些待核实。因此本文的表格与骨架是据此推出的设计建议,而不是对某个宿主行为的描述。
常见问题(FAQ)
技能文件里能不能直接写具体工具名和调用顺序?
不建议写死。按 GitHub 博文摘要的分层,工具属于运行技能的宿主;把调用序列写进技能文件,换宿主后这段就可能失效。更稳的做法是在文件里描述“要拿到什么信息、满足什么条件”,把具体工具交给宿主配置。
项目路径和权限声明放哪里?
放在技能文件之外。摘要把项目上下文与权限同样归到宿主一侧,因此路径、环境变量、凭据和权限声明应由项目级配置或宿主权限体系承载,技能文件只声明需要什么,不声明怎么获得。
参考来源
以上为本文写作时的参考资料,引用观点以原文为准。