Agent Skills 也需要 lockfile

Agent Skills 也需要 lockfile

你在 Cursor 里装了一堆 Agent Skills，.cursor/skills/ 目录躺在项目里。看起来还行。

直到出现这些问题：

新同事 clone 仓库，Agent 行为跟你本地不一样。排查半天，他磁盘上的 skill 版本更老。但你俩都是从同一个 repo 拉的。

有人手改了一个 SKILL.md，没走 PR review，CI 也没报错。两周后 Agent 开始胡说八道，溯源才找到那次改动。

重装、升级 skills 之后，没人说得清：现在磁盘上的内容，跟上周 CI 通过的那份，到底一不一样？

换成 npm 依赖，你会立刻想到 package-lock.json。

Agent Skills 是指令包，直接决定 AI 的行为。但它们一直缺同样的工程化手段。

skilllock 补这一层：装完 skills 之后，怎么锁、怎么验、怎么审计、怎么复现、怎么升级。

安装和锁定是两件事

Agent Skills 生态里的工具分工：

• APM、Vercel skills、skillpm 解决怎么装
• skilllock 解决装完之后怎么管（锁、验、审计、复现、升级）
• sklock 处理嵌套 skills/*/skills/* 目录 + closureHash

skilllock 不是安装器，不是 skill 仓库，也不替你做 code review。它做的是 DevOps / 供应链治理——类似 lockfile + npm ci + npm audit 那套。

skilllock 锁了什么

跑 skilllock lock，生成 skills.lock.yaml。里面记三样东西：

• 来源（git、npm、本地路径）
• 依赖关系（谁依赖谁）
• 每个文件的 sha256（改一个字节就能发现）

示例：

yaml

lockfileVersion: 2
skills:
  - name: demo-skill
    source: { type: apm, ref: org/repo/skills/demo-skill }
    dependencies: [helper-skill]
    files:
      - path: SKILL.md
        hash: sha256:0bf96dd1...
        size: 244

MCP、Rules 这类 context 也能锁进同一个文件（lockfile v2 的 context 段），避免 skills 锁了但 MCP 配置还在漂。

skilllock 默认用平铺目录（.cursor/skills/<name>/），依赖通过 SKILL.md frontmatter 里的 metadata.skilllock.dependencies 声明，不做 filesystem 嵌套发现。如果团队标准化了嵌套 skill 目录，可以看 sklock。两个工具可以一起用，但别对同一套 skills 重复 lock。

五分钟上手

前提：Node.js ≥ 20，项目里已经有 .cursor/skills/（或者准备开始管）。

bash

npm install -D skilllock
skilllock init              # 生成配置、测试模板、gitignore 建议
skilllock import            # 可选：从 apm.yml / package.json 导入 source 映射
skilllock scan              # 扫描现有 skills
skilllock lock              # 生成 lockfile
skilllock check             # 校验

把 skills.lock.yaml 和相关配置提交进 git。从此 lockfile 就是团队对「这个项目该用哪些 skills、内容是什么」的共识快照。

不想装到 package.json 也能试：

bash

npx skilllock@1.1.0 init
npx skilllock@1.1.0 lock
npx skilllock@1.1.0 check

CI 上加一道门禁

把下面这个文件加到 .github/workflows/skilllock.yml：

yaml

name: skilllock-check
on: [pull_request, push]
jobs:
  skilllock:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lz1834career/skilllock/action@v1.1.0
        with:
          command: check
          skip-tests: "true"

check 会串联 verify、validate、audit、test、drift、untracked 等检查。相当于给 Agent Skills 加了一道合并前门禁。

skilllock init 还会生成 weekly drift、auto-upgrade 等工作流模板，需要的话可以按需启用。

一个实验

跑通 skilllock lock 和 skilllock check。然后手动改 .cursor/skills/ 里任意一个 SKILL.md，改一个字。再跑 skilllock check。

CI 会红。skilllock explain 告诉你哪个 skill、哪个文件、怎么修。

lockfile 的意义就在这里：不是加流程负担，是把「Agent 用哪些指令」从口头约定变成可校验的工程资产。

新同事怎么复现

bash

git clone <repo>
cd project
npm install                # 如果 skilllock 在 devDependencies 里
skilllock reproduce
skilllock verify

离线环境：有网机器上跑 skilllock lock --snapshot，提交 .skilllock/snapshots/ 目录。离线机器用 skilllock reproduce 恢复。

日常操作

• 看依赖树：skilllock tree
• 生成 Mermaid 依赖图：skilllock graph
• 查某个 skill 从哪来：skilllock why <name>
• 安全扫描：skilllock audit
• 检查可升级项：skilllock outdated
• 自动升级：skilllock upgrade --apply --reproduce --check

完整命令见 docs/commands.md。

skilllock 还是 sklock？

• 要 CI 门禁、reproduce、audit、MCP/Rules lock、升级 → skilllock
• 要嵌套 skill 目录 + closureHash → sklock
• 两个都想用 → 安装器装 skill，然后 skilllock lock / check，别对同一套 skills 重复 lock

试试

• GitHub：github.com/lz1834caree…
• npm：npm install -D skilllock
• 示例项目：examples/demo-project
• 中文 README：README.zh-CN.md

如果团队已经在用 Agent Skills，从这三步开始：

bash

skilllock init
skilllock lock
skilllock check

把 lockfile 提交进 git，CI 里跑 check。