团队多人协同维护项目时，如何统一管理 skill

一个人使用 Agent 时，skill 装在自己的全局目录里，什么时候更新都可以。团队一起维护项目后，这种方式很快会出现问题：同一个任务交给不同的人处理，Agent 的行为却不一样；有人已经更新了规则，有人还在使用旧版本；出了问题以后，也很难确认当时到底加载了哪一份 skill。

我更倾向于把项目使用的 skill 当成项目依赖来管理。项目需要哪些 skill、来自哪里、使用什么版本，都应该跟代码放在一起，由 Git 记录变化。

先分清全局 skill 和项目 skill#

npx skills 通常有两种安装范围：

全局安装，放在用户目录下，适合个人在多个项目中都想使用的通用工具；
项目安装，放在当前项目的 .agents/skills，适合项目规范、代码审查、测试约定等和仓库强相关的内容。

全局安装可以这样做：

1
npx skills add <owner>/<repo> \
2
  --global \
3
  --agent codex \
4
  --skill <skill-name> \
5
  --yes

项目安装则不加 --global：

1
cd <project>
2

3
npx skills add <owner>/<repo> \
4
  --agent codex \
5
  --skill <skill-name> \
6
  --yes

团队协作时，真正影响项目交付结果的 skill 应该放在项目范围内。全局 skill 可以作为个人补充，但不能作为团队约定的唯一载体。否则，一个人执行 npx skills update -g，其他人不会自动得到同样的变化。

把 skill 和锁文件提交到仓库#

项目可以采用下面这种结构：

1
project/
2
├── .agents/
3
│   └── skills/
4
│       └── project-conventions/
5
│           └── SKILL.md
6
├── skills-lock.json
7
└── ...

.agents/skills 保存项目实际使用的 skill，skills-lock.json 保存安装来源和版本信息。安装完成后，将这两部分一起提交：

1
git add .agents/skills skills-lock.json
2
git commit -m "chore: add project skills"

锁定版本时，最好使用明确的 Git commit，而不是长期跟随某个浮动分支。这样做的意义和锁定 npm、Maven 依赖一样：今天能复现，几个月后也能查清楚当时使用的内容。

不同 Agent 的目录有时只是由 CLI 建立的链接或同步目录。团队应该把 .agents/skills 和锁文件视为项目的规范来源，不要把某台电脑上的全局目录当成真实配置。

更新应该走一次集中审查#

技能升级不适合由每个人在本机随手执行。比较稳定的流程是：指定一个维护人，或者由机器人定期检查；发现新版本后创建一个普通 PR，团队审查通过再合并。

项目级更新命令如下：

1
npx skills@latest update -p -y

更新时，CLI 会读取锁文件，根据来源、技能路径和内容指纹检查远程变化。检测到变化后重新安装，并更新锁文件中的记录。这个过程本身可以自动化，但合并前仍然应该看一遍 skill 的实际内容。

一个简单的升级流程可以是：

1
定期检查
2
    ↓
3
更新项目 skill 和锁文件
4
    ↓
5
查看 SKILL.md 及 references 的变化
6
    ↓
7
运行项目校验
8
    ↓
9
创建升级 PR
10
    ↓
11
合并后由所有成员同步

如果使用 GitHub Actions、Renovate 或其他定时任务，可以让它负责执行更新和创建 PR，不建议直接自动合并。skill 不只是普通的文档，它会改变 Agent 的判断和执行方式，升级内容值得经过代码审查。

在 CI 中检查环境是否一致#

新成员或一台干净环境可以根据锁文件恢复项目 skill：

1
npx skills@latest experimental_install

CI 里可以增加一个一致性检查，确认恢复结果没有让仓库内容产生额外变化：

1
steps:
2
  - uses: actions/checkout@v4
3

4
  - name: Restore project skills
5
    run: npx skills@latest experimental_install
6

7
  - name: Check project skills
8
    run: git diff --exit-code -- .agents/skills skills-lock.json

这类检查能尽早发现两种问题：锁文件已经更新，但项目中的 skill 内容没有同步；或者有人只修改了本地 skill，没有把变更提交到仓库。

新成员的初始化也可以固定成几步：

1
git clone <repo-url>
2
cd <project>
3
npx skills@latest experimental_install
4
npx skills list

这样新成员不需要根据口头说明逐个安装，也不会因为忘记某个全局 skill 而得到不同的 Agent 行为。

升级 skill 时重点看什么#

把 skill 升级当成一次小型依赖升级，至少检查这些内容：

来源是否仍然可信，仓库和维护者有没有变化；
SKILL.md 是否改变了适用范围、执行步骤或默认行为；
references、脚本和配置文件有没有新增读取、写入或网络操作；
示例命令是否仍然适用于当前项目；
是否影响项目已有的测试、提交和发布流程；
锁文件、实际目录和 CI 恢复结果是否一致。

如果只是更新文案，审查可以很快完成；如果 skill 新增脚本或扩大了操作权限，就应该按代码变更来处理，而不是因为它叫 skill 就跳过审查。

几个容易踩坑的做法#

第一，把所有东西都装成全局 skill。这样开始最省事，后面却很难排查“为什么我的 Agent 和同事的不一样”。

第二，直接引用远程仓库的主分支。主分支一旦变化，项目行为也可能在没有业务代码提交的情况下变化。至少应该通过锁文件记录版本，稳定后再按计划升级。

第三，只提交锁文件，不提交项目实际使用的 skill。新环境虽然知道来源，却仍然依赖网络和远程内容；如果远程仓库删除了某个版本，恢复就会变得不可靠。项目是否提交完整目录，要结合仓库策略和许可证确认，但不能让团队成员各自保留一份无法追溯的副本。

第四，升级后只看 CLI 的成功提示。命令成功不代表新规则适合当前项目，还是要看 diff，并跑一遍和 skill 相关的校验。

小结#

团队统一管理 skill，关键不是要求每个人每天手动升级，而是把 skill 纳入项目本身的版本管理：

项目级 skill 放进 .agents/skills；
用 skills-lock.json 记录来源和版本；
由一个维护入口定期升级，走 PR 审查；
新环境根据锁文件恢复；
CI 检查实际内容和锁文件是否一致；
全局 skill 只作为个人补充，不承担团队一致性。

这样做以后，skill 就不再是某个人电脑上的隐藏配置，而是项目可以审查、回滚和复现的一部分。Agent 的行为仍然会随着规则变化，但变化至少有明确的提交记录，也有机会在进入主分支前被团队看到。