本文记录一台同时使用 Claude Code 与 Codex 的开发机上，skill 管理暴露出的四类问题，介绍两款开源管理工具 vercel-labs/skills 与 xingkongliang/skills-manager，并逐项对照它们解决了哪些问题、哪些问题不在其覆盖范围内。结论先放在这里：安装、跨 agent 同步、升级这三件事可以完全交给工具；skill 之间的触发冲突和效果评测，两款工具都没有处理，需要 Claude Code 自带的 /skill-doctor 与 claude plugin eval 补足。
这次盘点得出的根源和直觉不同。直觉上的麻烦是 skill 装得太多，实际的麻烦是同一个 skill 没有唯一正本。机器上有 50 多个 skill，~/.claude/skills 与 ~/.agents/skills 两个目录里同名的 skill 中，有 13 个内容已经不一致，其中改动最多的一个两边相差 58 行。这些差异不报错，也不会提示，模型读到哪一份就按哪一份执行。
所以 skill 管理首先是一个 single source of truth 的问题，其次才是数量和质量的问题。工具的价值也应该按这个顺序衡量。
一台开发机上的四类 skill 管理问题
五个来源对应五套版本记录
盘点下来，机器上的 skill 有五个来源，每个来源用自己的方式记录版本：
| 来源 | 版本记录方式 |
|---|---|
| Claude Code plugin 市场 | installed_plugins.json，记录 git commit sha |
npx skills 安装 |
~/.agents/.skill-lock.json，记录源仓库、路径和目录 hash |
| 公司内部 skill 市场 | 一个 jsonl 文件，只记录安装时间 |
| 手动 git clone 后软链接 | 只有本地 clone 的 git log，最后一次 pull 停在半年前 |
| 自己编写 | 没有版本记录 |
「升级到最新版本」因此无法用一条命令完成。要回答「哪些 skill 落后了」，必须分别查五个地方，而其中两个来源根本没有可比较的版本号。
13 个 skill 的副本内容不一致
Claude Code 读 ~/.claude/skills，Codex 读 ~/.codex/skills，npx skills 把全局安装的正本放在 ~/.agents/skills。这三个目录里的同名 skill 本应是同一份内容，实际上多数是各自独立的目录，而不是指向同一处的软链接。
因此在一个目录里改了 skill，另一个目录不会跟着变。对比 ~/.claude/skills 与 ~/.agents/skills，13 个同名 skill 内容不同，修改时间也不同向。多数是 ~/.agents 一侧较新，但也有在 ~/.claude 一侧刚改过、~/.agents 一侧还停在两个月前的情况。没有任何一侧可以整体当作正本。
skill 指令与当前工作规则相互矛盾
有两个自己编写的发布类 skill，仍在指示模型调用一个已经停用的发布接口；另一个选题类 skill 把下游出图指向一个已经无法启动的脚本，而同一台机器上的出图 skill 明确写着「这个脚本启动必崩，不要再用」。
这类问题比副本漂移更隐蔽。skill 文件格式正确、能正常触发，只是内容过时了。格式校验只检查结构，不了解业务规则，发现不了这类问题。
21 个 skill 常驻约 3,200 个 token
Claude Code 官方文档说明，skill 的 description 始终加载进上下文，正文在调用时才加载。claude plugin details 显示，一个包含 21 个 skill 的第三方插件，仅 description 部分就让每个会话常驻约 3,219 个 token，无论这些 skill 是否被用到。
成本之外还有触发冲突。机器上有 4 个功能相近的生图 skill、4 个中文写作类 skill，description 里的触发词高度重叠。用户说「出张图」，模型在 4 个候选里选哪一个，取决于 description 的措辞和当次的上下文，结果不稳定。
vercel-labs/skills 与 skills-manager 的定位
按 GitHub 数据（2026-10-07），面向多 agent 的 skill 管理工具里，活跃度和用户量领先的是这两款：
| 工具 | Star | 最近提交 | 形态 | 支持的 agent |
|---|---|---|---|---|
| vercel-labs/skills | 33,248 | 2026-10-05 | CLI（npx skills） |
75+ |
| xingkongliang/skills-manager | 5,618 | 2026-10-04 | 桌面应用 + CLI，Rust 实现 | 54+ |
vercel-labs/skills 是一个包管理器式的 CLI，命令集为 add / remove / list / find / update，安装源可以是 GitHub 仓库、任意 git URL、本地路径或私有仓库。它的目标是把「装一个 skill」变成和装 npm 包一样的操作。
skills-manager 则是一个本地 skill 库。所有 skill 先进入中央目录 ~/.skills-manager，再由它部署到各个 agent。除桌面界面外，它附带一个与桌面端共用数据库的 CLI，并提供一个 manage-skills skill，让 Claude Code、Codex 等 agent 通过调用它来安装和部署 skill，而不是直接往 agent 目录里写文件。
另外两个常被提到的项目：numman-ali/openskills（10,776 星）的思路是生成 AGENTS.md，让原本不支持 skill 的 agent 也能读取 SKILL.md，但最近一次提交停在 2026-01-18，而 Codex 等主流 agent 现已原生支持 skill，其必要性下降；awesome-agent-skills-managers 收录了 112 个同类工具并标注安全评级，适合需要横向比较时查阅。
两款工具对四类问题的解法
副本漂移：正本加软链接
两款工具解决副本漂移的机制相同：只保留一份正本，各 agent 目录里放指向正本的软链接。vercel-labs/skills 的 README 把 symlink 列为推荐安装方式，理由是「Single source of truth, easy updates」；只有在不支持软链接的环境下才建议用 --copy。skills-manager 同样支持 symlink 与 copy 两种部署方式。
对已经漂移的存量，skills-manager 多做了一步。它的 CLI 提供 skills adopt ~/.claude/skills --dry-run，可以先预览如何把某个 agent 目录里的现有 skill 收编进中央库。部署时如果目标位置已有一个不归它管理的目录，它会拒绝覆盖，并以 TARGET_CONFLICT 错误码返回冲突路径，不会悄悄覆盖掉另一份内容。
需要说明的是，工具无法替你判断 13 个不一致的副本里哪一份是对的。收编之前，仍要人工逐个比对，选定正本。
来源分散：lock 文件与统一的 update
vercel-labs/skills 为每个 skill 在 lock 文件里记录源仓库地址、skill 在仓库内的路径和目录 hash。npx skills update 按这些记录拉取上游，-g 只更新全局、-p 只更新项目级。GitHub 私有仓库可以通过 GITHUB_TOKEN 或已登录的 gh 访问。
skills-manager 用 skills check --all 检查 git 来源的 skill 是否有上游更新，skills update --all 执行升级；对本地导入的 skill 则采用重新导入的方式。它还可以连接一个私有 GitHub 仓库做自动备份和多设备同步，同一个 skill 在两台机器上被同时修改时，不阻塞其余 skill 的同步，由用户在「保留本地 / 使用远端 / 两者都留」之间选择。
两款工具都管不到的是 Claude Code plugin 市场里的 skill 和公司内部市场里的 skill。前者仍由 claude plugin update 负责，后者走内部工具。五套版本记录可以收敛到三套，无法收敛到一套。
功能重叠与常驻成本：按场景启用
skills-manager 的 preset 功能可以把 skill 编成命名分组，在某个 agent 的作用域内一键启用或停用一整组。写作场景只启用写作组，开发场景只启用开发组，同时在线的 skill 数量下降，description 的常驻成本和触发冲突也随之下降。README 特别注明，应用 preset 是一次性复制，不是持续同步。
vercel-labs/skills 没有对应功能，只能通过 remove 或安装时的 -a 参数控制 skill 部署到哪些 agent。
skill 内容过时：两款工具都不处理
update 解决的是「本地版本落后于上游」，不解决「上游内容本身已经与你的规则不符」。上文那几个过时的 skill 都是自己编写的，它们本身就是上游。两款工具都不读取 skill 正文，自然不会发现其中引用了已停用的接口。
对这类问题，可行的做法是维护一张已废弃引用的词表（停用的接口名、已删除的脚本路径），在每次修改规则后扫描全部 SKILL.md。
管理工具未覆盖的冲突检测与效果评测
四类问题里，工具对副本漂移和来源分散处理得较完整，对功能重叠只提供了手动分组。skill 之间的触发冲突是否真实发生、某个 skill 是否真的提升了输出质量，这两件事需要另外的工具。
Claude Code 内置的 /skill-doctor 统计每个 skill 的上下文开销和调用次数，并标出从未被调用过的 skill。按官方文档，它要求 v2.1.252 以上，且只能在本地终端里运行。它回答的是「哪些 skill 该删」。
claude plugin eval 回答的是「skill 有没有用」。它读取 evals/ 目录下的用例，默认每个用例运行 3 次，用 haiku 作为评分模型，并自动增加一组不加载该 skill 的 baseline，报告两组之间的分差。分差接近零的 skill，即使格式完美、触发准确，也没有保留的理由。--max-cost-usd 可以限制单次评测的花费，--threshold 可以设定及格线并接入 CI。
评测的投入应当集中在自己编写、使用频率高的 skill 上。第三方 skill 的质量由其作者负责，对使用者而言，锁定版本、有计划地升级就足够了。
选型建议
只用命令行、不需要图形界面，选 vercel-labs/skills。它的用户量最大，官方的 skill 目录 skills.sh 也以它为安装入口，自己写的 skill 也可以放进私有 git 仓库，再用 npx skills add 以软链接方式部署到 Claude Code 和 Codex。
需要按场景切换 skill 组合、需要多设备同步，或者手上已经有一批漂移的存量要收编，选 skills-manager。它的 adopt 与 TARGET_CONFLICT 机制是专门为存量迁移设计的。
两者不宜叠加使用。它们各有一套中央存储，同时管理同一批 skill，会重新制造出两份正本，回到本文开头的问题。