最近帮一个多 agent 项目收拾代码，翻到skills目录时愣了半天。同一个技能，在项目根目录存了一份，在某个业务 agent 的专属目录里存了一份，在另一个团队的备份目录里还躺着一份。三份内容看着差不多，实际细节各有各的改法：一份换了指令措辞，一份改了工具调用的返回格式，还有一份是改到一半的中间产物。问了一圈，没人说得清哪份才是“当前生效”的版本。
这事不是我第一次遇到。多 agent 环境跑起来之后，skill 管理几乎必然会变成一团乱麻。原因不难理解：skill 本质上是“给 agent 用的插件包”，谁都想改起来方便，又都怕影响别人，于是复制一份自己改，成了最省事的做法。省事一时，后面就是持续还债。这篇文章把我踩过的坑、用过的办法、以及两款专门解决这个问题的开源工具做个完整拆解，希望能让你少走一段弯路。
1. 先拆现象：多 agent 里 skill 为什么总会各自为政
1.1 一个 skill 到底是什么
先把概念对齐一下。在 agent 开发里，skill 不是一个抽象名词，它通常是一个目录，目录里包含三样东西：描述文件（写上这个技能是干什么的、什么时候该用）、指令内容（告诉 agent 具体怎么执行）、以及可能附带的少量脚本或参考数据。我们常见到的结构大概是这样：
skills/ web-search/ SKILL.md search.py prompts/ refine.md这个目录会被 agent 框架在启动时扫描，然后注册成 agent 可以调用的“能力”。你可以把它理解成给 agent 装了一个“插件”，只是这个插件不是二进制，而是文本指令加脚本的组合。
问题恰恰出在“文本指令”上。文本是可以随意改的，太容易产生分支。如果一个 skill 目录被多个 agent 共享，任何一个人改一行字，都可能影响所有使用它的 agent。为了避免这种“牵连”，最常见的本能反应就是复制一份出来单独改。
1.2 “三份”是怎么来的
我复盘过一个典型的翻车现场，三份来源非常清晰。
第一份在项目根目录的shared/skills/，是当初立项时候定下的“标准版本”，由最早搭框架的人维护。
第二份在一个业务 agent 的agents/order-agent/skills/里，是某位开发者在调订单流程时觉得“共享目录不敢瞎改”，于是把整个 skill 复制进自己负责的 agent 目录里，然后在副本上调参。这看起来没有破坏别人，但副本开始独立演进。
第三份就更隐蔽了。出现在一个叫archive/的备份目录里，里面是某次大重构前全量拷贝出来的旧版本。后来有人排查问题时找资料，搜到这个旧版本，被里面一段写得更好的指令吸引，直接照着改进了自己的代码。但从没想过先把三份放到一起对比。
于是三份并存，各有差异，还互相引用。这个场景不是个例，我见过好几个人多 agent 项目的 skill 目录都是这种状态。
1.3 三份带来的实际问题
表面上只是文件重复，实际上会造成三层麻烦。
第一层是版本漂移。根目录那份升级到了 2.1.0，业务 agent 目录里的副本还停在 2.0.3。同一个动作，不同 agent 出来结果不一致：同一个搜索工具，一个按要求用旧格式解析结果，另一个按新格式解析，下游数据处理全乱了。
第二层是排查困难。agent 报错时，第一件事是搞清楚它到底加载了哪个 skill。但如果同一份 skill 散落多处，日志里显示的路径往往指向其中一个目录，你按路径去改，改完重启，发现行为没变——因为它实际加载的是另一份。这种“你以为改了，其实没改”的状态，调试成本极高。
第三层是隐性知识流失。最惨的一次是维护人离职后，没人知道三份里的哪一份才是“带线上验证过的那一版”。新接手的人基于错误版本继续迭代，等于把之前的 bug 修复全部丢掉。说到底，skill 失控不是文件问题，是“事实来源”问题。
2. 管理 skill 的正确思路和两款开源工具
2.1 核心思路：单一事实源、引用分发、一致性校验
要解决“存了三份”的问题，不能用“以后大家自觉一点”这种办法。人和人的习惯不同，自觉靠不住。正确思路是引入一套机制，把“唯一可改的地方”和“实际使用的地方”剥离开来。
我习惯把思路拆成三句话：
- 单一事实源：每个 skill 只允许存在一份可编辑的源头，其余地方都是那份源头的引用或副本。
- 引用分发：各 agent 目录里不该自己存一份，而是通过引用（软链）或拉取机制获取内容。
- 一致性校验：需要能随时检查“引用方拿到的内容”和“源头内容”是否一致，不一致就要报警或自动更新。
这个思路跟图书管理很像。图书馆里正本只有一本，读者借阅的是副本，正本改了，副本是否同步，由系统负责。如果每个读者都自己复印一本带回家改，那图书馆迟早乱套。
2.2 工具一：SkillUnify——把分散副本收拢成一份
第一款工具我先说 SkillUnify（化名），它解决的问题是“已经乱了的目录怎么收拾”。
它的定位是文件级收敛工具。做法是扫描你指定的多个目录，找出所有名字匹配到同一 skill 的文件夹，计算内容指纹（比如文件的 sha256），然后生成一份差异报告。报告里会标清楚哪几个目录里的 skill 完全一致、哪几个有差异、差异集中在哪些文件上。基于这份报告，你可以决定谁是“权威版本”，然后它会把其他副本替换成对权威版本的软链接，或者按你指定的策略同步过去。
我会推荐在存量项目上先用它做一次“清点+收口”。因为存量项目往往已经有多份副本，直接上引用管理工具会失败——引用管理器只知道认一个 source，但你先得决定哪份是 source。
SkillUnify 还有个相对实用的子命令，可以按“最新修改时间 + 版本号 + 内容相似度”综合打分，帮你判断哪份最可能是权威版本。这个打分不一定是最终决定，但用来快速定位基本不会错。
2.3 工具二：SkillLink——用配置声明各个 agent 该引用哪个 skill
第二款工具叫 SkillLink（化名），它解决的是“以后怎么持续管理”的问题。
SkillLink 走的是配置驱动。你写一个清单文件（比如skill-link.yaml），在里面声明每个 agent 目录需要哪些 skill、版本约束是什么、遇到冲突时按什么规则处理。执行同步命令后，它会自动把对应的 skill 内容放到指定目录里，并且记录一份缓存清单，用于后续校验。
这份清单文件是核心资产。新加入的 agent 不需要再手动复制 skill，只要在清单里登记一笔，执行一次同步，就拿到了和别的 agent 一致的技能内容。更有价值的是，它让 skill 依赖关系变得可见：谁在用哪些 skill、用的哪个版本，打开清单一目了然。
SkillLink 内部用的是一套本地缓存机制，它不一定直接改你的 agent 目录，而是在缓存目录里维护好文件后，再通过链接或复制放到目标位置。这样你随时可以删掉某个 agent 目录重建，只要清单还在，一条命令就能恢复所有 skill。
2.4 两款工具怎么选、能不能叠加
不用纠结“二选一”。我的习惯是分两步：先用 SkillUnify 完成历史清理，再用 SkillLink 建立长效机制。清理是外科手术，管理是日常保健，两个场景不同，可以搭配使用。
| 维度 | SkillUnify | SkillLink |
|---|---|---|
| 核心功能 | 扫描重复、生成差异报告、软链合并 | 清单声明、自动分发、版本约束 |
| 适用时机 | 存量项目，已经存在多份副本 | 新项目或清理后建立长效规则 |
| 使用方式 | 命令行扫描 + 交互确认 | 编辑配置文件 + 执行同步 |
| 典型输出 | 替换为软链接的目录 | 各 agent 目录内的同步结果 |
| 维护成本 | 低，一次性清理 | 中，清单后续需要随需求更新 |
我的实际建议是：如果你的项目已经有超过两个 agent 目录，直接从第一步开始——把 SkillUnify 跑一遍，看清楚到底有多少重复。没有“三份”问题之前，你根本不知道自己重复了多少。
3. 实操：把同一个 skill 从三份收敛成一份
3.1 第一步：先盘点，别急着删
面对三份 skill 目录，最忌讳的事情就是“凭感觉删掉不用的那份”。你感觉不用的那份，可能正是某个线上 agent 正在加载的。必须用工具得出客观结论。
开始之前先在每个可疑目录跑一下指纹计算，生成 SKILL.md 和辅助文件的哈希值。以我的经验，用sha256sum是最直接的，但目录一多就麻烦。SkillUnify 的扫描命令会自动递归计算，我演示一下核心过程：
skillunify scan --root . \ --include "shared/skills/**" \ --include "agents/*/skills/**" \ --include "archive/**"执行完后，它会输出一个分组结果，我拿典型场景举例：
Group: web-search [v2.1.0] shared/skills/web-search <- 修改时间最新 [v2.0.3] agents/order-agent/skills/web-search [v2.0.3] archive/skills-backup/web-search Diff summary: SKILL.md: changed (7 lines) search.py: identical看到这个结果，基本就锁定了：shared/skills/web-search是权威版本，archive里那份是旧版备份，order-agent目录里的副本比权威版本落后一个版本。此时不要直接删order-agent里的副本，因为 agent 的加载路径可能硬编码指向那里。
正确做法是先生成一份内容差异报告，仔细看一眼 SKILL.md 那 7 行改了什么，确认线上行为依赖的是哪份逻辑。如果确认权威版本正确，再进入下一步合并。
3.2 第二步：用 SkillUnify 做去重与软链
确认权威版本无误后，执行合并。合并的核心动作是把非权威位置的 skill 替换成指向权威位置的软链，这样 agent 加载路径不变，但实际内容只有一个来源。
skillunify unify --source shared/skills \ --target agents/order-agent/skills \ --mode link \ --symbol web-search参数选择上有讲究：
--mode link表示使用软链接，而不是复制。软链的好处是源头一改，目标自动可见，不需要反复同步。代价是如果 agent 框架判定目标是一个“独立目录”，有些框架不会跟随软链递归扫描，需要验证。--symbol web-search是告诉它只处理这个 skill，避免影响目录里其他内容。
执行完后，去order-agent/skills目录里看一下，web-search已经变成一个软链。再用skillunify verify验证一下路径引用是否有效：
skillunify verify --root . --follow-links这个命令会检查所有链接指向的源头文件是否存在、内容哈希是否匹配。这一步别省，很多问题都是链接建好了但源头路径写错，或者 agent 目录是相对路径导致找不到目标。
如果某个 agent 框架死活不认软链，备选方案是--mode copy，但这样又会回到“副本漂移”的老路。我的建议是优先排查框架配置，看有没有选项可以放开对链接目录的扫描，而不是直接退回复制。我在实际项目里遇到过一次，最终通过把链接目录排除出“watch 目录列表”、改成“只在加载时解析一次”解决了问题。
3.3 第三步：用 SkillLink 做 manifest 管理
清理完成后，立即引入 SkillLink 建立长效机制。这一步不能拖，拖一周很可能又有人手动复制一份。
创建一个全局清单位文件，命名随意，我用的是skill-link.yaml：
version: 1 defaults: provider: local source_dir: ./shared/skills strategy: symlink agents: - name: order-agent path: agents/order-agent/skills skills: - web-search - name: inventory-agent path: agents/inventory-agent/skills skills: - web-search ->skilllink sync --config skill-link.yaml再查每个 agent 目录，会发现web-search已经变成对shared/skills/web-search的链接。也就是说，以后谁来改 skill，只需要改shared/skills里的那份，所有 agent 立刻拿到最新内容。
更实用的是它的校验命令：
skilllink check --config skill-link.yaml --strict--strict会同时检查链接是否存在、内容哈希是否一致、以及配置里有没有声明了但目录里缺少的 skill。建议把它挂进 CI 或者写进提交前的检查清单，防止有人绕过流程手动创建重复副本。
3.4 一套可复用的最终目录结构
全部收口之后，推荐的目标结构长这样：
project/ shared/ skills/ web-search/ SKILL.md search.py agents/ order-agent/ skills/ web-search -> ../../shared/skills/web-search inventory-agent/ skills/ web-search -> ../../shared/skills/web-search >agents: - name: order-agent path: agents/order-agent/skills skills: - name: web-search version: 2.1.0 pinned: true有了 pinned，SkillLink 在检查时发现源头版本变化，会提示“已锁定版本与源不符”，而不是悄悄覆盖。我的心得是：凡是线上 agent 在用的 skill，一律加 pinned。开发期随便更，上了线就必须锁版本，这是多 agent 环境稳定性的底线。
4.3 问题三：改动 source 后线上 agent 还在用旧内容
如果你用的是软链，理论上 source 改了，目标文件内容会跟着变。但很多 agent 框架启动时会把 skill 内容预加载到内存里，改文件不会热更新。所以“我改了 shared 里的文件，为什么 agent 行为不变”不是链接问题，是缓存问题。
我的做法是：
- 先确认文件内容是否已经变了：
cat shared/skills/web-search/SKILL.md | head -n 20，用哈希对比一下。 - 再确认目标链接内容是否同步：
cat agents/order-agent/skills/web-search/SKILL.md | head -n 20。 - 两者一致但 agent 行为没变，直接重启 agent 或者清掉它的 skill 缓存目录。
SkillLink 的check命令可以在重启前帮你确认同步是否完成，省去“清缓存结果发现文件根本没同步”的来回折腾。
4.4 避坑清单
最后放一张我整理出来的速查表，是我在处理多个项目后沉淀下来的：
| 场景 | 正确做法 | 错误做法 |
|---|---|---|
| 清理历史副本 | 先扫描指纹，再确认权威版本 | 凭文件名直接删除 |
| 软链不可用 | 改框架配置允许跟随链接 | 退回--mode copy |
| 线上 agent 的 skill | 加pinned锁定版本 | 让版本随 source 自动漂移 |
| 容器内挂载目录 | 统一用相对路径建立软链 | 用宿主机绝对路径 |
| 新增 skill | 放进 shared 目录 + 更新 manifest | 直接复制到某个 agent 目录 |
| 改动 source 后 | 跑 check + 重启 agent | 只改文件不验证 |
两个独家经验再额外说下。
一是不要直接在 agent 正在运行的目录里改 any 文件。即使有软链，强行写入运行中目录也可能产生部分写入、半更新状态。先把文件放到临时目录，校验完整后再替换。SkillLink 的同步逻辑就是先写缓存再原子替换，这个设计我后来在自己项目里也照搬了。
二是给每个 skill 的 metadata 里加一个 version 字段。很多 SKILL.md 只有指令文本，没有版本。加一个version: 2.1.0字段，配合 SkillLink 的 pins 机制，等于给每个技能明确了身份。没版本号的 skill，在多人协作里只能靠猜。
5. 这个内容后续还可以怎么扩展
说回最开始的场景。帮那个项目清理完那三份 skill 之后，我又顺手做了一件事：把skill-link.yaml提交进版本库，并写了一条简短的 README 说明提交前要跑skillunify verify。之后的一周里，没有出现新的重复副本。
如果你也是多 agent 项目，而且已经感觉到 skill 目录开始失控，我的建议是先跑一遍扫描，用报告说话，不要急着删文件。多数情况下，你实际重复的 skill 数量比你想的要多，差异也没你想的那么小。把“同一个 skill 只存一份”这个原则变成具体的流程，比靠自觉靠谱得多。
