Skills管理最佳实践，skills-lock.json

我用 skills-lock.json 管 verysmallwoods 仓库里的 Agent skill 有一阵了 - 最高峰装到二十来个，最近做了一轮清理，砍到 frontend-slides、open-design、prototype、yourwebs、personal-chinese-writing-style 五个常用的。借这次清理的机会聊一聊锁文件 - 它是什么、谁在背后维护、解决了什么问题、我在项目里怎么用，以及一些自己摸出来的实践。期望对大家有所帮助。

skills-lock.json 解决什么问题

先交代一下：Agent skill 就是给 AI agent 用的可复用能力包，通常是一份 SKILL.md（或者一组配套文件），告诉模型「碰到 X 任务时按这套套路做」。Claude Code、Vercel 的 agent toolkit 等都在这个范式上跑。

skill 多了之后，两个问题马上冒出来：

• 重现性：我装的版本，团队成员、CI、未来的我，能不能装到一模一样的那一份？
• 完整性：skill 是公开仓库里的 markdown，今天 add 一次、明天上游改一行，我本地这份就跟当初看的不是同一份了。

skills-lock.json 就是为这两件事而生。它是项目级的锁文件，跟 package-lock.json 之于 npm、composer.lock 之于 PHP 的位置一致 - 把「我现在装的到底是哪一份」写死，并用 SHA-256 哈希做兜底校验。

锁文件背后

围绕 skills-lock.json 的这套工具链来自 Vercel Labs - 锁文件格式和 npx skills CLI 都是这个团队在维护，跟 package-lock.json 由 npm 团队维护一个位置。这意味着格式相对稳定，CLI 也在持续迭代，可以当作长期方案用，不用担心是某个个人项目某天没人维护。

管理上也很直接：CLI 写入，git 跟踪，人不动手。改 skill 集合的命令（add、update、remove）才会写这份文件；experimental_install 方向相反 - 它读锁文件，把里面记的版本还原到 .agents/skills/ 下，不反向改锁。我把锁文件跟代码一起 commit；手改它的后果跟手改 package-lock.json 一样 - 下次 CLI 跑会跟实际安装对不上。

文件长什么样

直接给我仓库根目录 skills-lock.json 里的两条：

{
  "version": 1,
  "skills": {
    "frontend-slides": {
      "source": "sugarforever/frontend-slides",
      "sourceType": "github",
      "skillPath": "SKILL.md",
      "computedHash": "bbf3664513fba5704c63a1b1425d0fc71c10ff48df7e419b193167299bed3931"
    },
    "personal-chinese-writing-style": {
      "source": "sugarforever/01coder-agent-skills",
      "ref": "main",
      "sourceType": "github",
      "skillPath": "skills/personal-chinese-writing-style/SKILL.md",
      "computedHash": "19b40f9180c02ab9a9706e30c6e7a2aa9abcce70f942a89e8f5bf49769526521"
    }
  }
}

字段意思都直白：

• source：skill 从哪儿来。GitHub repo 路径，owner/repo 形式。
• sourceType：来源类型。目前是 github。
• skillPath：仓库内 SKILL.md 的具体位置。同一个 repo 可以暴露多个 skill。
• computedHash：装入时计算的 SHA-256。上游内容变了，哈希会对不上。
• ref（可选）：跟踪的 git ref。默认是仓库 HEAD；如果想钉到具体分支、tag 或 commit 上，就显式写出来 - 上面那个 personal-chinese-writing-style 就钉在 main 分支。

锁文件本身不存 skill 内容；skill 的实际文件落在 .agents/skills/<name>/ 下。锁文件只记一件事 - 我引用的是哪一份。

npx skills 三件套

日常基本就这三个动作：

# 新增 skill：从 GitHub 拉下来，把这次安装写进 skills-lock.json
npx skills add <owner>/<repo>

# 对比本地哈希和上游：看有没有更新可用
npx skills check

# 按锁文件精确还原所有 skill：团队同步 / CI 必用
npx skills experimental_install

experimental_install 的名字最容易让人误读 - 听上去像 install 类操作，会顺手更新锁文件，但它的行为其实跟 npm ci 一回事，严格按锁文件装，不接受锁文件和实际安装不一致的状态。换台机器、换条分支、CI 拉新代码，跑一次就知道环境是不是齐的。

我在这个仓库里的几条实践

下面是我在 verysmallwoods 里的真实做法。不是放之四海皆准，但每条都是为了解决具体问题。

把锁文件提交进 git。 skills-lock.json 跟代码一起进版本控制是这个机制能用起来的前提 - 不 commit，等于没用锁文件。所有变更只通过 CLI 产生：add 写入、check 比对、install 还原。

不要为了对称硬拆锁文件。 我一开始也在 backend/ 子项目里单建了一份 skills-lock.json，想着让前后端各管各的，跟两份 package.json 对称。后来发现 backend/ 是个独立部署的 Cloudflare Worker，根本不跑 Agent skill，那份锁就是个空架子，删了 - 现在整个仓库一份锁就够。判断标准很简单 - 子项目有没有它自己、跟主项目不重叠的 skill 集合？没有就别拆。

升级流程：先 check 再 add。 想看上游有没有更新就跑 npx skills check，它会列出本地哈希和上游不一致的条目。看完输出再决定要不要升级；要升就用 npx skills add 重新装，锁文件随即同步更新。直接 add 也能用，但先跑一遍 check 能避免「不知道改了什么就升上去」。

新机器只做一件事：experimental_install。 拉代码、装依赖、npx skills experimental_install，三步走完 Agent skill 这一层就齐了。这是锁文件最大的意义 - 让「环境对得上」从靠记忆变成靠文件。

source 的可信度永远第一，hash 是兜底。 锁文件解决的是「上游今天的样子跟我当初安装时是否一致」，它不替你判断「这个 repo 一开始就值不值得信」。你 add 的是一个 GitHub repo 里的 SKILL.md，那个 repo 本身的可信度你得自己看。Hash 抓的是篡改，不是来源风险。

用锁文件就等于绑定一套 CLI。 引入 skills-lock.json 之后，整个项目的 skill 管理就跟 npx skills 这套工具绑在一起 - 团队成员、CI、未来的我，都得用同一套 CLI 去 add / update / install。绕过它（手装 skill、手改锁文件）锁文件马上跟实际安装对不上，重现性也就没了。这不算坏事，但用之前要清楚：选了锁文件，就选了配套的 CLI。

---

• Vercel Labs skills CLI：github.com/vercel-labs/skills
• Skills 注册表：skills.sh