多 Agent 并行干活，Skill 目录一冲突就全乱：单一真源 + 镜像同步的完整解法

本文简介：

同一个项目同时用 Cursor 和 WorkBuddy 维护，AI 技能（Skill）该放哪？放 .cursor/skills 还是 .workbuddy/skills？我一开始两边各建一份，结果很快尝到苦头：改了真源另一份没跟上、某个 AI 根本调不到那份技能、git 仓库被三份重复内容撑爆。

这篇文章不讲概念，只讲落地：先把各家到底扫哪个目录查清楚（这一步结论很反直觉），再给出「单一真源 + 自动镜像」的方案、完整操作步骤、以及一份能直接抄走的同步脚本。附我实测踩过的坑清单。

结论先行

三句话：

1. 问题的本质不是「该用哪个目录」，而是「多份物理文件必然发散」。 只要允许同一个 Skill 存在于多个目录，早晚会分叉——所以必须先确立唯一真源，再解决「各家怎么都能看到它」。
2. 本机实测结论（2026-10-20）：WorkBuddy 项目级 Skill 只认 .workbuddy/skills/，不扫 .agents/，而且没有任何配置项能改扫描路径。 所以「让 WorkBuddy 也去扫 .agents/skills」这条路走不通，镜像不能省。
3. 最终解法：.agents/skills/ 作唯一真源（只改这里）+ tools/sync_skills.py 自动镜像到另外两个目录（只读）+ 每 30 分钟计划任务兜底 + 镜像不进 git。

下面把每一步都摊开讲清楚。

一、为什么「各建一份」必然出事？

每个 AI 工具都约定了一个自己的 Skill 发现目录。项目里先后接入了 Cursor 与 WorkBuddy，两者目录名不同；如果每个工具都在自己的目录下建 Skill，同一个能力就会分裂成多份物理文件。

关键提醒：上表最后一行「换电脑后行为不一致」是最容易被忽视、但杀伤力最大的一条。很多人的项目在同机时跑得好好的，一换机器、一换 AI 工具就集体失灵，根因就是这些手工目录既没同步也没入库。

二、各家到底扫哪个目录？我把扫描路径查了一遍

要定方案必须先查清 WorkBuddy 到底扫哪些目录，不然全是猜。我查了两处：

• 程序包 app.asar 里的扫描路径常量；
• ~/.workbuddy/.skill-list-cache.json 里的 watch.dirs 字段。

结果如下：

同时确认：~/.workbuddy/settings.json 里只有 sandbox / claw / plugins 相关字段，没有任何配置项能改 Skill 扫描路径。

关键事实（2026-10-20 实测）
WorkBuddy 项目级 Skill 只认 .workbuddy/skills/，不扫 .agents/；且无配置项可改。
因此「单一真源 + 自动镜像」不是权宜之计，是唯一可行解。

2.1 两层放法（最终定案）

既然项目级必须靠镜像，那就分两层管理，各归其位：

为什么用户级 ~/.agents/skills/ 不用镜像？因为它是文件级目录（真实文件，不是链接），各家都能扫到；一旦放进去，一份就覆盖所有项目。

三、最终解法是什么？单一真源 + 智能镜像

整体结构长这样（箭头是同步方向，镜像只读）：

    真源（唯一可写）
    .agents/skills/          ← 所有新增 / 修改只在这里发生
         │
         │  tools/sync_skills.py    每 30 分钟自动跑
         │  规则：mtime 比较，覆盖前自动备份，冲突不覆盖
         ▼
    ┌────────────────┬────────────────┐
    │ .workbuddy/    │ .cursor/       │   镜像（只读）
    │   skills/      │   skills/      │   目录内含提示文件，禁止直接改
    └────────────────┴────────────────┘
         │                  │
         ▼                  ▼
    WorkBuddy            Cursor / Codex
    （只扫这个）        （兼容扫描）

3.1 为什么要镜像，而不是目录联接（junction / symlink）

考虑过用符号链接代替拷贝，两个理由否决：

• 部分扫描器会跳过 symlink —— 链接建了也可能扫不到，等于白建；
• 链接不随 git 走 —— 换机器后链接全部失效，等于把同一个问题换个地方复现一次。

3.2 为什么镜像不进 git

镜像内容与真源完全相同，入库就是制造三份同一内容、每次提交还要处理重复改动的冲突。做法是：经 git rm -r --cached 移出索引（磁盘文件保留），并在 .gitignore 中排除：

# Skill 镜像目录：真源唯一在 .agents/skills/（2026-10-20）
# 由 tools/sync_skills.py 生成，不进 git，避免同一 skill 两份物理文件
.workbuddy/skills/
.cursor/skills/

换设备后由同步器一次性重建镜像，干净且无冲突。

四、具体怎么落地？四步操作步骤

4.1 日常：修改或新增一个 Skill

标准动作
三步，永远只做第 1 步；第 2 步有自动兜底，做了更快；第 3 步只是保险。

1. 在真源里改：.agents/skills/<skill名>/ 下编辑 SKILL.md 或 scripts/。
   编辑前先确认自己在真源路径，不是镜像路径——镜像路径下会有提示文件提醒。
2. 立刻同步（可选，30 分钟内自动也会做）：

& "C:\Users\Administrator\.workbuddy\binaries\python\envs\default\Scripts\python.exe" tools\sync_skills.py

3. 提交：把真源改动提交到 git；镜像不入库，不用管。

& git -C $base @who commit -a -m "更新 skill：<skill名> <改了什么>"

4.2 命令行参数

4.3 新增一个 Skill

1. 在 .agents/skills/<新skill名>/ 下建目录，写 SKILL.md。
   文件名必须是 SKILL.md，同步器靠它识别 Skill 目录——这是最容易漏的一步。
2. 加 scripts/ 等子目录按需。
3. 跑一次 sync_skills.py，两个镜像自动出现该 Skill。
4. 提交真源。

4.4 换电脑 / 新 agent 第一次接入

# 1) 拉取仓库（真源随之而来）
# 2) 重建镜像（镜像不在 git 里，必须本地重建）
& "C:\Users\Administrator\.workbuddy\binaries\python\envs\default\Scripts\python.exe" tools\sync_skills.py

# 3) 验证
& "C:\Users\Administrator\.workbuddy\binaries\python\envs\default\Scripts\python.exe" tools\sync_skills.py --check
# 期望输出：新增 0 / 覆盖 0 / 一致 N / 冲突 0（未修改）

4.5 自动兜底：30 分钟计划任务

已注册 Windows 计划任务 Project-SkillSync，每 30 分钟自动执行一次同步。即使某个 agent 改完 Skill 忘了跑同步命令，最多 30 分钟也会自动拉齐。

# 查看任务
Get-ScheduledTask -TaskName 'Project-SkillSync'
Get-ScheduledTaskInfo -TaskName 'Project-SkillSync'

# 停用（不再自动同步）
Disable-ScheduledTask -TaskName 'Project-SkillSync'

五、同步器怎么防止误覆盖真源？

同步器最核心的一条规则是不盲目覆盖。判断依据是文件修改时间（mtime）：

5.1 产出物位置

六、遇到问题怎么排查？排障手册

6.1 症状 → 原因 → 处理

6.2 验证机制是否正常

# 快速自检：应输出"新增 0 / 覆盖 0 / 一致 N / 冲突 0（未修改）"
& "C:\Users\Administrator\.workbuddy\binaries\python\envs\default\Scripts\python.exe" tools\sync_skills.py --check

# 计划任务是否在跑
Get-ScheduledTaskInfo -TaskName 'Project-SkillSync'   # LastTaskResult 应为 0

# 镜像里有没有提示文件
Get-ChildItem .workbuddy\skills\ -Filter "_真源在*"

七、同步脚本的核心代码长什么样？

完整脚本见文末付费资源包（含同步脚本、计划任务安装脚本、AGENTS.md 纪律条款与 gitignore 片段），这里贴出最关键的冲突判定部分——这是整套方案里最需要理解的地方：

if filecmp.cmp(s, d, shallow=False):
    counters['same'] += 1
    continue
sm, dm = s.stat().st_mtime, d.stat().st_mtime
if args.force or sm >= dm:
    # 真源较新 → 以真源为准，覆盖前先备份
    bk = BACKUP_ROOT / stamp / sk.name / rel
    bk.parent.mkdir(parents=True, exist_ok=True)
    shutil.copy2(d, bk)
    shutil.copy2(s, d)
else:
    # 镜像较新 → 不覆盖，留给人工判断
    conflicts.append(
        f'{mirror.name}/{sk.name}/{rel} 镜像更新于 {dm:%Y-%m-%d %H:%M}，'
        f'真源更新于 {sm:%Y-%m-%d %H:%M} → 未覆盖，请人工确认'
    )

八、怎么让 AI agent 自觉只改真源？

我把这几条写进了项目的 AGENTS.md，这样任何 agent 接手都自动知道，不用每次交代：

1. 要新增或修改 Skill，只改 .agents/skills/；不要直接改 .workbuddy/skills/ 或 .cursor/skills/。
2. 改完可跑 tools/sync_skills.py 立即同步；不跑也会在 30 分钟内自动同步。
3. 镜像目录不是真源；不要把镜像里的改动当成本人的工作成果。
4. 需要跨项目通用的 Skill 放 ~/.agents/skills/（用户级），不用镜像。
5. 同步器在覆盖前会把旧版备份到 tools/_sync_backup/<时间戳>/，改错了能回滚。

第 5 条那层兜底很重要：正因为「只改真源」是一条需要靠自觉遵守的纪律，同步器才必须做到「覆盖前先备份」——哪怕哪天 agent 判断失误，代价也只是一次恢复，不是丢失。

九、目前这套方案的落地状态如何？

遗留说明
本项目曾出现 .agents/skills/typesafe-ai 与 .cursor/skills/typesafe-ai 两份内容相同的副本。已逐文件比对确认一致后去重，真源保留一份，镜像由同步器统一生成，后续不会再出现手工副本。

FAQ：关于 Skill 目录冲突，读者最常问的几个问题

1. 到底该用 .cursor/skills 还是 .workbuddy/skills？

这两个都不是理想答案。理想答案是 .agents/skills/——它是跨工具的事实标准（AGENTS.md 规范），WorkBuddy 虽然目前只扫 .workbuddy/skills，但可以通过镜像机制读到真源。.cursor/skills 是 Cursor 的私有约定，别的工具不认。所以正确做法是：真源放 .agents/skills/，再同步一份到各工具目录。

2. 直接建软链接（symlink/junction）不就行了？为什么要写同步脚本？

软链接在跨平台上有三个硬伤：一是 Windows 管理员权限与开发者模式限制，git 也不记录链接目标；二是各工具扫描时对链接的处理不一致，有的会跳过符号链接目录；三是链接一旦断了，报错信息很难懂，排查成本高。同步脚本虽然多一层，但行为可预期、冲突有报告、覆盖前有备份，在多 agent 协作场景里更稳。

3. 同步会不会把我的改动覆盖掉？

默认不会。同步器按 mtime 比较：真源比镜像新才覆盖，镜像比真源新则跳过并记为冲突，写进 last_conflict.txt 留给人判断。覆盖前还会先把镜像旧版备份到 tools/_sync_backup/<时间戳>/，改错了能回滚。只有显式加 --force 才会无视时间戳强制覆盖。

4. 换一台电脑后 Skill 会消失吗？

按本文这套方案不会——真源在 .agents/skills/ 并随 git 提交，新机器 clone 下来跑一次 tools/sync_skills.py 就有镜像了。但如果没有真源、只在 .cursor/skills/ 里手工存过一份，那只 clone 那一侧，那份就会在换机后彻底消失，同时出现「agent 说没有这个技能」的现象。

5. 用户级的 ~/.agents/skills/ 需要做镜像吗？

不需要。用户级目录是真实文件目录（不是链接），WorkBuddy、Cursor、Codex 都能直接扫到。一份就覆盖所有项目，放进去就全局可见。只有项目级才需要镜像，因为各家只扫自己项目目录下的那份。

6. 同步脚本要多久跑一次？会不会覆盖掉我正在写的东西？

本项目用的是 Windows 计划任务 Project-SkillSync，间隔 PT30M，即每 30 分钟一次。同步时如果发现镜像比真源新（说明有人直接在镜像里改过），不会覆盖，只记冲突。真正需要立即生效时，手动跑一次即可，脚本是幂等的。

作者与更新说明

我是汪斌（老汪），制造业财务出身，专注成本核算、业财融合与 Excel BI 落地，运营「老汪洞察」。这篇文章来自我在真实项目里踩的一次坑——同一个项目被 Cursor 和 WorkBuddy 同时维护，Skill 目录各建一份，很快发散；我花时间把各家的扫描路径逐一查清，才定下「单一真源 + 自动镜像」这套做法，再让 Agent 帮我把同步脚本和排障手册补齐。更新于 2026-10。

汪斌带你开公司 | 老汪洞察 | 小微之家会计服务 · www.accunion.cn

结语

多 Agent 并行干活的最大成本，不是模型能力，而是状态一致性。同一个项目被两三个 AI 工具交替维护时，任何「能改的地方不止一处」的设计，最终都会变成「改了一处忘了另一处」。

所以我的做法是：把「真源在哪」这件事写死在目录约定里，把「同步」这件事交给脚本和计划任务，把「别乱改」这件事写进 agent 行为准则里。 三层各管一段，剩下的就是照着跑。

如果你也在多 AI 工具之间来回切换，这套做法可以直接抄走。