Spec Kit 生成的技能终于能追溯版本
从 1.4.2 起,Spec Kit 将生成版本写入 SKILL.md,核心技能记录工具版本,扩展和预设记录各自的版本。升级 Spec Kit 后,磁盘上已有的技能文件仍需单独更新。
AI 深度解读
升级了 GitHub Spec Kit,Claude 或 Codex 仍可能照着旧版 SKILL.md 干活。项目配置显示 1.4.2,磁盘上的技能却可能还停在 1.4.1。只要旧指令还能执行,这种版本错位就可以一直没有报错。
Spec Kit 1.4.2 开始给生成的技能写入版本号。原文用 speckit-plan 说明了这项改动为什么要落在技能文件里,以及 skill-check 怎样用版本和来源发现过期副本。平时会把技能复制到代码仓库的团队,可以直接用这套思路排查更新有没有落到实际文件上。
为什么版本号要写进 SKILL.md
Spec Kit 原来就在 .specify/integration.json 里记录自己的版本。升级 Spec Kit 时,已生成的技能文件可以原样留在磁盘上。项目配置回答的是「这次用的是什么版本的工具」,而技能文件自己的版本才能回答「代理正在读哪一版指令」。
下面是 Spec Kit 1.4.2 生成 speckit-plan 时写入的文件头。
---
name: speckit-plan
metadata:
author: github-spec-kit
source: templates/commands/plan.md
version: 1.4.2
---
看最后一行 version: 1.4.2,它记录的是生成这份技能的版本。核心技能使用 Spec Kit 的版本,扩展和预设技能使用各自组件的版本。Agent Skills 规范已有 metadata 字段,这次直接在里面加键。作者 11 月 12 日发起讨论,13 日应维护者要求提交功能申请,16 日通过评审,17 日实现合并,1.4.2 同日发布。
查更新还需要知道原件在哪里
skill-check 0.5.0 会读取 Spec Kit 技能里的版本。下面是原文展示的提醒,说明 Claude 或 Codex 用到旧版 speckit-plan 时,用户会看到什么。
[skill-check] The skill "speckit-plan" is out of date: installed 1.4.1, latest v1.4.2.
Run `specify self upgrade`, then `specify integration upgrade claude` in this project.
第二行给了两步命令。specify self upgrade 更新工具,specify integration upgrade claude 在当前项目更新 Claude 集成。对扩展和预设,skill-check 会跳过这套以 Spec Kit 发布版本为基准的检查,因为它们各有自己的版本。
对普通的技能副本,metadata.source 可以指向上游仓库里的技能目录。有了这个地址,skill-check 会先比较版本,再比较内容和提交历史。这样,即使发布者改了文件却忘了把 metadata.version 从 1.2.0 往上调,检查仍有机会发现更新。Spec Kit 示例里的 templates/commands/plan.md 是组件内部路径,给普通技能补来源时,原文用的是可定位到上游目录的仓库地址。
我的判断
把版本写进产物这点说得对。项目级版本适合回答「团队升级到了哪一版」,文件级版本适合排查「代理实际加载了哪一版」。原文给了发布记录和一条具体的提示示例。至于检查能覆盖多少历史副本、能减少多少漏升级,作者没有给对照数据,这部分属于经验判断。
团队如果已经把技能统一放在一个仓库里,并通过固定提交分发,提交记录就能承担一部分追溯工作。metadata.version 和 metadata.source 的优势出现在文件被单独复制之后。另一个实际前提是团队可能改过本地副本。原文没交代检查工具会怎样呈现这种差异,收到提示后仍应先看改动,再决定如何同步。
能拿来做什么
- 下次升级 Spec Kit 后,挑一份团队常用的
SKILL.md,把文件头的metadata.version和.specify/integration.json对照一下,再确认代理加载的是哪份文件。 - 如果你在团队内分发代码审查或项目规划技能,发布时一起写入版本和上游来源。已经复制进仓库的技能,可以先确认原件,再给本地副本补上
metadata.source。 - 想在 Claude 里试检查,可以依次运行
/plugin marketplace add louis8408/skill-check和/plugin install skill-check@skill-check。Codex 对应的是codex plugin marketplace add louis8408/skill-check和codex plugin add skill-check@skill-check。按原文说明,工具采用 Apache-2.0 许可,只提示更新,既无服务端和遥测,也不会阻止技能运行或修改文件。