aduhappy/multi-agent-project-skill

多 Agent 协同项目骨架（跨软件可续接）

一句话安装（用户让你"装这个 skill"时自主执行）

来源仓库：https://github.com/aduhappy/multi-agent-project-skill。clone 到本工具的 skills 目录即装好（无其他依赖）。

不同工具的 skills 目录不同，请按工具选对路径：

工具	用户级 skills 目录	项目级 skills 目录
ZCode / Codex CLI	~/.agents/skills/	<项目>/.agents/skills/
Claude Code	~/.claude/skills/	<项目>/.claude/skills/
Cursor	N/A（用 rules）	.cursor/rules/（现代格式）或 .cursorrules（legacy）

通用原则：

• Windows 下 ~ = %USERPROFILE%。
• 用户级 vs 项目级拿不准时默认用户级（装一次处处可用）。
• 目录不存在先创建再 clone。clone 完告诉用户新开一个会话即可触发本 skill。

这技能干嘛

在项目根目录生成一套软件无关的纯 Markdown 协同骨架——一个权威入口 + 若干薄指针 + 自包含任务卡 + 收工规矩。换 Claude / Cursor / Gemini / ZCode / Copilot 任何一个，agent 进来读同一份入口就能接上前任工作，不丢上下文、不互相覆盖。

核心原则四条：

1. 真相只有一份：AGENTS.md 是唯一权威入口；其他工具的约定文件（CLAUDE.md / GEMINI.md / .cursorrules / copilot-instructions.md）全是 3 行薄指针，指向 AGENTS.md。
2. 细节外链、入口要短：AGENTS.md 控制在 1–2 屏，每个新 agent 都得读完。细则下沉到 文档/ 下的专题文档，入口只放指针。
3. 纯 Markdown + 相对路径：不依赖任何软件专属语法，换工具不破。
4. 信任但验证：agent 自检不够——关键产物必须由主控或另一 agent 独立抽验（守恒/边界/格数/量级/一致性）通过才进下一棒。这是多 agent 链路可信的基石。

何时触发

• 用户说"开新项目/新课题""怎么组织文档让 AI 协同""AGENTS.md 怎么写""多个 agent 接力"。
• 现有项目 agent 经常问重复问题、找不到状态、覆盖彼此产出。
• 用户要把"手工总结的协同经验"固化成可复用结构。

怎么用（两种模式）

模式 A：从零生成骨架

1. 问清（一次性问全，别挤牙膏）：项目根目录、一句话目标、要兼容哪些 AI 工具、是否云同步目录、涉及哪些数据源。
2. 加问一条硬约束清单："列出本领域'不可混用'的维度（口径/单位/坐标系/分辨率/时期/林龄分层等）。写成硬规则，后续所有 agent 必须遵守。"——这是最常被忽略但一错就全错的铁律。
3. 从 assets/ 复制 AGENTS.md 到根目录，填入用户给的内容。
   • 占位符规则（重要）：用户明确给的信息直接填；用户没给的，优先给合理默认值（基于项目主题推断）并简短标注"默认值，可改"；只有"用户特有的、没法合理推断"的细节（如具体 DOI、密码、账号）才留 【待填】。判据：AGENTS.md 正文里 【待填】 越少越好，理想是 0 个。
4. 按用户勾选的工具，复制对应薄指针文件（CLAUDE.md / GEMINI.md / copilot-instructions.md 等），内容统一是"以 AGENTS.md 为准"；Cursor 用户推荐用 .cursor/rules/multi-agent.mdc（现代格式），.cursorrules 为 legacy 备用。用户没勾的工具不要生成。
5. 建 文档/任务规划_<主题>.md（从 assets/任务规划_模板.md 复制）。如果项目有多个任务卡，同时拷入 assets/任务卡_README.md（任务卡目录索引模板，列依赖链和当前状态）。每张任务卡末尾自带『📋 派发提示词（复制即用）』块——把卡里字段填进去，用户复制即可贴给任何 agent 冷启动执行，不用每次重写委派话术。建卡时顺手填好这段。
6. （可选）按需建：文档/委派任务模板.md（从 assets/委派任务模板.md 复制，给主控 agent 派活用）、文档/决策记录/（存放 ADR）、文档/词汇表.md（项目术语）。注意：这些是可选模板，小项目跳过，别让入口变臃肿。
7. 推导数据集目录：从用户描述的数据源拆分——每类数据一个目录（例：用户说"MODIS + Landsat"→ 建 MODIS/ 和 Landsat/ 两个目录；用户说"问卷 + 实测"→ 建 问卷/ 和 实测/）。每个数据集目录放 来源.txt（从 assets/来源.txt 复制）。没明确数据源的项目可跳过这步。
8. 代码归位：建 scripts/ 目录 + scripts/README.md（从 assets/scripts_README.md 复制）。把用户已有的脚本列表填进去（如果有），或留空等后续 agent 填充。同时拷入 check_handoff.py（从 assets/check_handoff.py 复制）——收工交接自检脚本，agent 每次收工跑 python scripts/check_handoff.py 验证 §3/§4/STATUS 已更新。在 AGENTS.md §5 铁律里约定"脚本不散落根目录"。
9. 建 STATUS.md（从 assets/STATUS.md 复制）——空模板，第一个 agent 收工时填增量 handoff（本 agent 做了什么/动了哪些文件/踩了什么坑）。
10. 把用户的环境、约束写成 §铁律、§路径约定。
11. 跑完后告诉用户：骨架生成了哪些文件、有哪些"默认值"需要他确认、有哪些 【待填】 需要他补。

模式 B：诊断已有项目

B1：烂项目修补（零文档或文档混乱）

用户已有项目但协同乱——agent 反复问重复问题、互相覆盖、找不到状态。先读现有 README/任何文档/目录结构，对照 §文件骨架 和 §AGENTS.md 的板块 检查缺什么，给出全量修补清单（缺薄指针？入口缺失？任务卡不自包含？没来源.txt？没收工规矩？）。用户确认后补齐。先读后改，绝不直接覆盖已有文件。

B2：好项目增强（已有好文档，只缺薄指针）

用户已有完善的项目文档（如 AI_COLLABORATION_PLAN.md / README.md / 详细 wiki），但 AI 工具不会自动读它（Codex/Claude 默认读 AGENTS.md，不会主动发现自定义文件名）。只加一个 AGENTS.md 薄指针（3 行），指向已有文档；再按用户勾选的工具加对应的薄指针文件（CLAUDE.md 等）。不动任何已有文档。判据：加完后，新 agent 进门 → 读 AGENTS.md → 跳转到已有文档 → 获得完整上下文，无需用户手动说"先读 XX 文件"。

文件骨架（生成后长这样）

<项目根>/
├── AGENTS.md                          ← 唯一权威入口（顶部 TL;DR 3 行 + 七板块，所有工具默认读）
├── STATUS.md                          ← 增量 handoff（本 agent 做了什么/动了哪些文件/踩了什么坑，收工落盘）
├── CLAUDE.md                          ← 薄指针 → "以 AGENTS.md 为准"
├── GEMINI.md                          ← 薄指针（同上，可选）
├── .cursorrules                       ← 薄指针（Cursor 用，可选）
├── .github/copilot-instructions.md    ← 薄指针（Copilot 用，可选）
├── 文档/
│   ├── 任务规划_<主题>.md             ← 自包含任务卡（含"交付前必做"清单 + 可选建议模型）
│   ├── 任务卡_README.md               ← 任务卡目录索引（依赖链 + 当前状态表，可选）
│   ├── 委派任务模板.md                ← 给 AI agent 委派任务的标准话术（复制填，可选）
│   ├── 决策记录/                      ← 关键技术决策（可选，见 advanced.md）
│   └── 词汇表.md                      ← 项目术语（可选）
├── <数据集名>/                        ← 每个数据集一个目录
│   ├── 来源.txt                       ← DOI/URL/日期/口径/单位
│   └── ...
├── scripts/                           ← 代码归位（推荐：脚本不散落根目录）
│   ├── README.md                      ← 每个脚本一句话：干嘛/输入/输出/谁写的
│   └── check_handoff.py               ← 收工交接自检脚本（跑这个验证 §3/§4/STATUS 已更新）
└── 进度日志.md                        ← 带日期戳的变更流水（可选）

AGENTS.md 的板块（顺序即优先级）

照 assets/AGENTS.md 模板填。顶部先有一个 TL;DR 块（3 行：当前阶段/下一步/阻塞） 让新 agent 扫一眼就知状态；下面 8 个板块（模板编号 1–7，其中路径约定单独编号为 §5.5，因为太重要不能和铁律混在一起）：

0. TL;DR（进门速读）——3 行：当前阶段、下一步、阻塞。每次收工更新。新 agent 不用读完全文就知道干到哪了。
1. 一句话北极星——这项目到底干嘛、给谁、什么基调（语气、投稿/交付目标、别耽误哪条主线）。
2. 当前故事/方法——最新定下来的方向 + 核心方法 + 最近换过什么、为什么。
3. 现在在哪——每次收工更新，1–5 条带日期戳的累计快照。这是接力最关键的交接点。增量细节下沉到 STATUS.md，本节只留累计状态。
4. 任务看板——[ ]/[x] + 谁负责 + 依赖（T1→T2，哪些可并行）+ 已知风险。
5. 铁律/约定——违反会返工的：环境调用、绘图/数据规矩、命名、口径、收工规矩。含"新 agent（含子 agent）进门第一件事：读完 AGENTS.md 再动手"。 5.5. 路径约定——大文件去哪、小产物回哪（防多 agent 撞车、防云同步爆炸）。单独成节，别埋进铁律。
6. 深读指针——细节去哪个文档（任务细则、决策记录、词汇表、任务卡索引）。
7. 环境/工具——完整工具路径怎么调、env 锁。

STATUS.md vs AGENTS.md §3 的分工（防重叠）：STATUS.md 记增量（本 agent 这一轮做了什么、动了哪些文件、踩了什么坑）；AGENTS.md §3 记累计快照（当前整体进度，1–5 条）。两者不重复——STATUS.md 是"自上次以来的变化"，§3 是"现在整体到哪了"。

决策登记表（强烈推荐，别只当 advanced）：把具约束力的决策用一张有界、可 grep 的表收口——一行一决策：ID | 决策 | 取值/口径 | 理由 | 日期 | 证据链接 | 取代了谁。放 AGENTS.md §6 指针下，或 §3 紧邻处。它和散在 STATUS 长叙事里的自由式 ADR 不同：有界（一决策一行，永远读得完）、可查（grep 关键词秒命中权威行）、可追（supersedes 链）。这是防"决策被埋没在长日志里、或被某个滞后脚本悄悄覆盖"的关键一层。模板见 references/advanced.md §1。

跨软件能续的硬要求（7 条）

1. 纯 Markdown + 相对路径 + 标准文件名——别用某软件专属语法、别硬编码绝对路径。
2. 数据带 来源.txt（DOI/URL/下载日期/口径/单位/已知问题）——换人换 agent 都能溯源。
3. 收工规矩写进铁律——每个 agent 退出前更新 §现在在哪 + §任务看板 + 写/更新 STATUS.md（增量 handoff：本 agent 这一轮做了什么、动了哪些文件、踩了什么坑，不重复 §3 的全量快照）。收工时跑 python scripts/check_handoff.py 自检——验证 §3 日期新鲜、TL;DR 已填、STATUS.md 非模板、STATUS 日期 ≥ §3 日期、薄指针存在；另含两条 advisory（决策登记表是否存在、多脚本口径常量是否漂移）。全过才算交接合格。
4. 路径纪律——"大文件进工作盘、小产物回仓库""复制不剪切，别动别人正在跑的路径"。
5. 新 agent（含子 agent）进门第一件事——读完 AGENTS.md（含 STATUS.md）再动手，不靠对话历史、不凭记忆乱猜。STATUS.md 会越长越没人读全——所以任何具约束力的决策（口径/排除清单/选定参数）必须上浮到 AGENTS.md §3 或决策登记表这层有界、必读的位置，别只躺在 STATUS 的长叙事里。取数/建模/复现前先查这层，别去信某个脚本里的硬编码。
6. 关键数字与口径参数单一来源、防漂移——关键数字（均值/百分比/面积等）只在 STATUS.md 或 AGENTS.md §3 一处写定，别处只引用不复述。口径参数/样本集/排除清单（用哪些点、剔哪些、阈值多少）同理：抽进唯一的 config（config/参数.yaml 或一张权威表），所有脚本读它、严禁在多个脚本里各自硬编码——两个脚本对同一集合编码不一致，是最隐蔽的接力事故源（自检看不出、格式检查也看不出）。收工前核对所有文档与脚本间一致性，同一数字差 1% 以上、或同一集合成员不一致，即视为 bug，必须先对齐再交。
7. 坏产物与被取代的脚本一并退役隔离——发现某 agent 的产物错了（数据/图/数字），立即：①目录改名加 _DEPRECATED 后缀或放入 _作废/ 子目录；②在 AGENTS.md §5 铁律节顶部用红字 > ⚠️ 【作废】<路径> 标注（别标在 §3——§3 是累计快照，坏产物标记应和铁律/规范放在同一节）；③更新 §4 看板状态为 [x] + 标注"作废"；④更新 STATUS.md 反映作废；⑤被某决策取代的旧脚本/方法同样退役——脚本顶部加 # _DEPRECATED → 见 <权威脚本/决策> 注释，别让它当成活口径把下家钓进去。绝不只靠记忆说"那个别用"——下游 agent 静默复用坏产物、或抄了一个滞后脚本的口径，比没产出更致命。

💡 一条真实接力教训（这 3 条规则就是这么来的）：某 agent 要重拟一条曲线，从一个滞后脚本里抄了样本集——那脚本还保留着早该剔除的坏点，而"剔除该点"的决策只躺在 600 行 STATUS 的深处，且两个脚本对它的编码恰好相反。结果该点把 R² 从 0.5 拖到 0.27，对外汇报被推翻。事后看，三处都本可拦住：决策没上浮到有界必读层（规则 5）、口径集合在多脚本里各自硬编码而非单一 config（规则 6）、被取代的旧脚本没打退役标记（规则 7）。信滞后脚本、不信决策记录是这类事故的共同根因。

核心工作流（agent 接力全流程）

一个典型的多 agent 交接生命周期包含 5 个显式步骤。跳过第③步"独立复核"是多数链路污染的根本原因。

① 委派 → ② 执行 + 自检 → ③ 独立复核 → ④ 接收入库 → ⑤ handoff 落盘

步骤详解

① 委派（主控 → 执行 agent） 用标准话术（见下文模板或 assets/委派任务模板.md）明确：读什么、做什么、不碰什么、输出落哪、疑点记哪。

② 执行 + 自检（执行 agent） 执行任务，做完跑一遍 DoD（验收清单），确认输出完整、格式对、无报错。

③ 独立复核（主控或另一 agent 抽验关键数字） 别信自检——执行 agent 自检全过不代表产物无误（已被反复证明不够）。

• 主控或第三 agent 抽验关键数字：守恒（输入总和 ≈ 输出总和？）、边界（有无越界/未裁净？）、格数（行数/像元数符合预期？）、量级（单位是否差 10³？）、一致性（各文档中同一数字是否一致？）。
• 通过→进第④步；不通过→退回执行 agent 修复，并记录 ADR。
• 判据："独立复核通过"是进入下一棒的阀门，不是可选项。

④ 接收入库 确认无误的产物正式落位，更新 来源.txt（如果是新数据）和 scripts/README.md（如果是新脚本）。

⑤ handoff 落盘 更新 AGENTS.md §3 现状 + §4 看板 + 写 STATUS.md。保证下个 agent 仅靠仓库 markdown 能续上。

💡 短链路（1–2 个 agent、产物简单）可跳过第③步；产出影响论文结论或下游管线的，必须走完 5 步。

两层续接（缺一不可）

• 硬续接（主依赖）：仓库里的 Markdown，软件无关，任何 agent/人都能读。这是真相源。
• 软续接（增强）：记忆层（Cursor memory / Claude memory）加速检索，但别让核心结论只活在记忆里——必须落回 Markdown。

判据：把所有记忆层删光，下个 agent 只靠仓库 Markdown 也能接上 → 合格。

给 AI agent 委派任务的标准话术

每次委派新 agent 时，用统一格式开头——效果远好于自由发挥。照 assets/委派任务模板.md：

请先阅读 AGENTS.md（含 STATUS.md 了解当前状态）。 不要修改原始数据（<路径>）和已有核心代码（<路径>）。 本次任务只处理阶段 X。 如果发现疑点或新问题，记录到 <指定文档>，不要直接修正。 输出落在 <指定路径>。 本任务已知坑：[列已知风险点] 交付前必自查：[守恒/边界/格数/量级…，逐条过]

这个模板的核心价值：让新 agent 冷启动时立即知道该读什么、不该碰什么、出问题往哪汇报。其中"已知坑"和"必自查"两栏是实战验证过的关键增量——引导 agent 在报完成前自拦截常见错误类型，大幅降低缺陷率。

对于影响论文结论或下游管线的关键任务，在话术末尾追加「交付后安排独立复核」指示（模板末段有进阶示例）。

派发提示词随卡走（推荐）：别让用户每次现填这段话术——每张任务卡末尾内置一份填好的『📋 派发提示词（复制即用）』块（见 assets/任务规划_模板.md T1 末尾）。卡建好时就把目标/边界/输入输出/已知坑/自查/收工填进去，用户要派活时直接复制那段贴给任何 agent（含跨工具、跨技能）即可，零现编。委派任务模板.md 只作字段含义参考。

进阶板块（按需启用，见 references/advanced.md）

核心七板块之外，这些在项目变大时有用，别一上来就全堆上：

• 决策记录（ADR）——记"为什么弃用某方法"，防止下个 agent 重新踩坑、重新质疑已定的事。
• 词汇表——项目特有术语/缩写，新 agent 不用猜。
• 进度日志——带日期戳的变更流水，比 §现在在哪 更细。
• 验收具体化——DoD 写成可运行检查命令，而非"完成了就行"。
• 标准 handoff 摘要——现状/下一步/未解决风险/关键文件路径。
• 命名约定 + 幂等性——输出文件带 _v1/日期/坐标系；可重跑脚本幂等（有缓存跳过）。
• 环境锁——conda env 钉 environment.yml，防跨机器重建漂移。
• 数据快照/不可变输入——原始数据只读带 hash，所有人在副本上动。
• 填好的 AGENTS.md 样例——references/example_filled_AGENTS.md，一个完整范例（虚构项目）。照着填比空模板直观得多。

自定义提醒

• 这套骨架来自真实科研项目（多 agent、多数据集、长管线、云同步）实战。复制后按领域裁剪：纯前端项目可砍掉 §路径约定 的"工作盘"部分；单 agent 小脚本项目 §任务看板 可简化。
• 模板占位符统一用 【待填】，填完删掉。
• 薄指针文件内容统一（见 assets/CLAUDE.md），别在每个里写不同规则——那会破坏"真相只有一份"。
• 不要覆盖用户已有的 AGENTS.md；如果是模式 B 诊断，先读后改、增量修补。