Community编程与开发github.com

agent-coordinator

用于将 Claude 作为“大脑”、其他编码 Agent 作为“双手”的项目协调技能。在新项目、接手现有项目、导入研究结果、发布版本或询问状态时使用。

agent-coordinator 是什么?

Agent Coordinator 是一项用于 Claude Code、Cursor、Codex 等平台的 AI Agent 技能,其核心理念是将工作按强度和成本拆分:Claude 作为“大脑”,负责规划里程碑、编写 Agent 提示词、审查分支并合并与打标签;编码 Agent(如 Antigravity/Gemini、Codex 或其他 Claude)作为“双手”,负责研究、跟踪、调查、大型修复和批量代码;用户作为“测试者”,在真实机器上运行构建并报告所见;仓库作为“记忆”,所有学到的内容都存储在提交的文档中,而不是任何聊天记录中。该技能支持多种模式:新项目启动(Kickoff)、接手现有项目(Adopt)、导入研究结果(Research Import)、发布版本(Release)、继续会话(Continue)和状态查询(Status)。它提供了完整的文档模板、检查脚本和提示词模板,确保 Agent 间的协作标准化、可追溯。关键的工作流程包括:编写自包含的提示词(包含目标、分支、已知事实、任务、工具、约束、停止条件、验收检查和报告模板),审查 Agent 的工作时进行多步验证(检查报告、工具版本、重新运行测试、抽查引用、手动检查输出),并将发现的知识以经验教训的形式固化到 AGENTS.md 或检查脚本中。

兼容平台✓Claude Code✓Codex CLI✓Cursor✓Antigravity✓Gemini CLI
npx skills add https://github.com/Trooper-code/Trooper-s-Coordinator-Skills/tree/HEAD/skills/agent-coordinator

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Agent 协调器(Claude 作为大脑)

按强度和成本拆分工作:

  • Claude = 大脑。 规划里程碑,编写 Agent 的提示词,审查其工作,合并并打标签。
  • 编码 Agent = 双手。 进行研究、跟踪、调查、大型修复和批量代码。
  • 用户 = 测试者。 在其真实机器上运行构建并报告所见。
  • 仓库 = 记忆。 所有学到的内容都存储在已提交的文档中,而不是任何聊天记录中。

Claude 节省其 token 用于判断。它不启动新的调查或自行进行重大 bug 修复——这些任务通过提示词交给 Agent。

模板和脚本适用于以下每个文件:此技能的 templates/ 文件夹(包含在发布包中),或 templates/ 在 https://github.com/Trooper-code/Trooper-s-Coordinator-Skills。某些模式的详细信息在此技能的 reference/ 文件夹中;当该模式出现时,请阅读该文件。

脚本存放位置。 项目将其检查脚本保存在仓库根目录的 scripts/ 中,或保存在 docs/scripts/ 中。始终检查这两个位置(detect-mode.py 会报告使用的是哪个)。此技能中的每个 scripts/... 路径均指项目使用的那个文件夹。新项目除非用户要求使用 docs/scripts/,否则使用 scripts/。切勿移动项目现有的脚本。

选择模式

用户说 / 仓库有模式
"status","我们到哪了"状态(如下)
"发布 v…","切一个发布版本","打标签此处"发布:遵循 reference/release.md
"导入研究",粘贴了深度研究结果研究导入:遵循 reference/research-import.md
仓库有 docs/HANDOFF.md继续:阅读 HANDOFF.md、状态板及其指向的文档,然后执行其中的“首要做的事”
仓库有代码或文档,但没有 HANDOFF.md接手(如下)
空仓库(只有 README/LICENSE/.gitignore)启动(如下)

如果你能运行命令,python templates/scripts/detect-mode.py <repo> 会决定最后三种模式,并列出仓库已有和缺少的工作流文件。

状态

用于“使用 agent-coordinator。状态。”或“<项目> 进行到哪了?”。刻意轻量:

  • 只读取 docs/MILESTONES.md 和 docs/HANDOFF.md(以及如果你有仓库则运行 git log --oneline -5)。
  • 用大约五行回答:当前里程碑及其状态,正在进行的工作及谁在负责,最后测试的结果,下一步,以及任何等待用户的事项。
  • 除非被要求,不要审查、测试或打开其他文件。

启动(新项目)

例如 /agent-coordinator 开始一个新项目:<名称>。仓库:<URL 或文件夹>。目标:<...>。编码 Agent:<...>。

  1. 获取访问权限。 如果没有仓库,请求仓库(GitHub 链接或本地文件夹)。对于本地文件夹,同时请求删除权限(git 会创建和删除 .lock 文件)。
  2. 范围确定。 如果目标确实不明确,提出 1-3 个尖锐问题:"完成"是什么样子,用户拥有哪个编码 Agent 及其哪些工具,以及硬约束(平台、语言、绝不能提交的内容)。否则直接开始。
  3. 搭建记忆框架(不要覆盖已存在的文件):
    • AGENTS.md,填写特定 Agent 的部分(参见“Agent 的规则文件”)。
    • docs/MILESTONES.md,docs/HANDOFF.md(包含工具版本),docs/DECISIONS.md, docs/research/INDEX.md,docs/prompts/,docs/reports/TEMPLATE.md,CHANGELOG.md。
    • scripts/(如果用户偏好则为 docs/scripts/):检查脚本(参见 reference/scripts.md)。
    • 安全和发布:templates/hooks/pre-commit 复制到 scripts/hooks/pre-commit(钩子本身不提交,因此用户只需安装一次:cp scripts/hooks/pre-commit .git/hooks/pre-commit,或对应的 docs/scripts/... 路径),以及 .github/workflows/checks.yml 和 .github/workflows/release.yml。钩子和工作流会从这两个文件夹中找到脚本。
  4. 为 M1 编写第一个提示词到 docs/prompts/M1-<slug>.md,并对其运行 check-prompt.py。如果 M1 纯粹是研究,Agent 的工作是填充 docs/research/,而不是编写代码。
  5. 提交框架,附带清晰的信息。
  6. 简要回复: 里程碑列表,粘贴到 Agent 的一行指令,钩子安装命令,以及“完成后告诉我;它的报告将在其分支上的 docs/reports/ 中”。

接手(现有项目)

例如 /agent-coordinator 接手我的现有项目。仓库:<URL 或文件夹>。编码 Agent:<...>。

了解项目已知的内容,据此规划,只添加缺失的文档。扫描是读取文档和仓库结构,而不是调查代码:任何需要跟踪的工作都交给 Agent。

  1. 获取访问权限,如同启动步骤。
  2. 扫描(预算:约 15-20 次工具调用;detect-mode.py 一次完成盘点)。读取,不跟踪:
    • 顶层布局,构建文件和测试设置(语言,如何构建和测试,哪些工具版本);
    • README,docs/ 下的所有内容,RESEARCH.md,NOTES.md,TODO.md,ROADMAP.md,CHANGELOG.md;
    • 现有的 Agent 规则文件(AGENTS.md,CLAUDE.md,GEMINI.md,.cursor/rules/,.agents/rules/);
    • 同时检查 scripts/ 和 docs/scripts/:项目已有的检查脚本及其位置;
    • git log --oneline -30,分支和标签:上次做了什么,哪些是半成品;
    • TODO/FIXME 注释,如果列出成本较低(git grep -n "TODO\|FIXME")。
  3. 盘点。 将现有内容映射到工作流的文件。重用能完成工作的内容:将现有路线图链接到 MILESTONES.md,保持现有研究文档在原地并建立索引,将缺失的部分添加到现有规则文件中而不是替换它。只创建缺失的内容。绝不覆盖、移动或重命名用户的文件。
  4. 标记你学到的东西。 来自现有文档或注释的事实在被测试之前是未经验证的。记录文档与代码之间的矛盾作为差距。将你能看到的过去选择(选择的库,决定的格式)记录到 DECISIONS.md 中,但只有在文档说明原因时才记录;否则将它们列为未解决的问题。
  5. 对整个仓库运行 check-safe-to-publish.py。如果有任何标记的内容,先告知用户:从历史记录中删除已提交的文件由他们决定。
  6. 提前规划: 完成半成品分支,修复失败的测试,关闭 TODO,填补研究空白。将带有完成标准的新里程碑写入 docs/MILESTONES.md。真正的判断点(重写 vs. 修复,哪个功能优先)→ 在承诺计划前提出 1-3 个尖锐问题。
  7. 第一个提示词。 代码的大部分没有文档记录 → M0:调查(Agent 将它们映射到 docs/research/ 和索引,每个声明都引用并标记)。否则为 M1。
  8. 编写 docs/HANDOFF.md,运行 check-handoff.py,并在一次提交中提交新文档(例如“添加协调器文档”),保持每个现有文件的行尾符。
  9. 简要回复: 你学到的东西,创建或扩展的文件,计划,任何需要用户决定的事项,以及粘贴到 Agent 的一行指令。

Agent 的规则文件 (AGENTS.md)

固定的规则存放在仓库根目录的 AGENTS.md 中,因此提示词只需要携带特定于任务的内容。它包含始终/从不规则、工具版本和标记规则、停止条件、报告格式,以及一个特定于 Agent 的部分。

特定于 Agent 的约束是必需的。 每当用户命名其编码 Agent 时(启动、接手或切换),填写 ## Agent-specific constraints: <agent>:

  • 从配置文件开始位于 templates/agents/(Antigravity,Codex,Claude Code,Cursor,通用)。保留其已确认/未验证的标签。
  • 询问用户安装了哪些工具,并删除他们没有的工具。
  • 如何加载规则。 如果配置文件说 Agent 读取另一个文件,则创建它描述的指针。如果不确定,说明情况并在每个提示词中保持 AGENTS.md 首先出现在“首先阅读”下。
  • 高权限工具的权限限制,以及已知的怪癖。
  • 当用户或 Agent 纠正了配置文件中的事实时,在 AGENTS.md 中修复它,并建议也向上游修复共享的配置文件。

里程碑和分支

  • 将里程碑规模的工作分解成里程碑。每个里程碑都有自己的功能分支。
  • Agent 从不合并。 Claude 审查分支,然后在用户测试并确认其工作正常后合并并打标签(例如 m5-p4a)。
  • 在 docs/MILESTONES.md 中跟踪状态(里程碑、带日期的进度日志、当前的“下一步”步骤)。

编写提示词

提示词放在 docs/prompts/<MILESTONE>-<slug>.md 中,已提交,自包含(Agent 没有本次聊天的上下文)。章节,如 templates/PROMPT.md:

  1. 首先阅读:AGENTS.md 优先;然后 docs/research/INDEX.md 和本任务需要的章节;任何它触及的 DECISIONS.md 条目。
  2. 目标:一两句话。
  3. 分支:分支名称,以及从哪个标签开始分支。
  4. 已知事实:精确的路径、地址、偏移量、值;每个都标记为已确认或未验证,并附有证据。
  5. 任务:编号。如果 check-research.py 发现基于旧工具版本的事实被本任务依赖,则重新检查它们是一个任务。
  6. 工具:适合此任务的 Agent 工具及其原因。
  7. 特定于任务的约束:仅限 AGENTS.md 未提及的内容。
  8. 如果以下情况则停止并报告:AGENTS.md 中的停止条件,加上本任务的特定条件。
  9. 验收检查:哪些测试必须通过;每个声明都引用其证据。
  10. 报告:docs/reports/<MILESTONE>-<slug>.md,提交在分支上。

对其运行 check-prompt.py,修复它报告的问题,然后给用户在 Agent 中使用的一行指令,例如“阅读并遵循 docs/prompts/M5-p4b-save-format.md。”

命名工具。 过程技能(例如,超能力:systematic-debugging,test-driven-development,verification-before-completion);分析或逆向工程工具包(其声明需要通过模拟、测试或真实运行来证明;对于用户文件,保持高权限功能为只读);多 Agent "swarm" 模式仅用于可拆分为独立部分的大型任务——一个 swarm 提示词需详细说明每个工作者负责的部分、文件及其完成标准,并说明验证者将运行仓库的测试。

审查 Agent 的工作

从分支读取报告:git fetch origin <branch> 然后 git show origin/<branch>:docs/reports/<file>。只有在报告不存在时才要求用户粘贴摘要。

Agent 以前犯过错误。验证,不要信任:

  1. 对报告运行 check-report.py。报告未通过则返回给 Agent,除非差距很小。
  2. 将报告中的工具版本与 docs/HANDOFF.md 对比。不匹配在没有解释之前是一个 bug。
  3. 亲自重新运行其测试和证明。
  4. 抽查它引用的地址、偏移量和声明,与真实文件和日志进行核对。检查已确认的发现是否被标记([confirmed @ <branch> | tool=version])并且新的章节是否在研究索引中;运行 check-research.py。
  5. 手动解码或检查其输出。
  6. 将结果列为 bug,然后是 差距,最后是吹毛求疵。

预算规则: 如果检查一个声明需要超出 Agent 引用的新跟踪(大致超过 ~10 次工具调用),则停止。将其放入下一个提示词中。

如果 Agent 停止了,不要重做其工作:决定它需要什么(访问权限、文件、修正的事实、更小的任务),并将其写入下一个提示词。

审查后:

  • 工作正常 → 给用户精确的测试步骤(做什么,他们应该看到什么)。一旦他们确认,合并、打标签、在 CHANGELOG.md 的 ## Unreleased 下添加一行,并在文档中记录。
  • 不工作 → 编写后续提示词,将 bug 和差距作为任务。
  • 相反,放弃在两轮审查失败后,或者当修复朝错误方向发展时:保留该分支(如果用户同意,重命名为 abandoned/<name>),在研究文档中作为经验教训记录原因,保留任何已确认的发现,并从最后一个好的标签编写全新的提示词。

保持记忆敏锐

  • 决策。 当用户在选项之间做出真正选择时(格式、库、重写 vs. 修复),在 docs/DECISIONS.md 中添加条目:已决定、已拒绝、原因、何时重新考虑。在重新讨论已解决的问题之前,先阅读其条目;新事实应创建新条目来覆盖旧条目。
  • 研究索引。 每个研究主题在 docs/research/INDEX.md 中有一行,指向其文件和章节。首先在那里查找;当章节移动时,保持其最新。
  • 版本感知的事实。 已确认的事实带有它们被证明时的标签和工具版本的标记。每当工具版本表发生变化时,运行 check-research.py 并将重新检查列出的事实放入下一个提示词。
  • 经验教训成为规则。 第二次遇到的教训在 HANDOFF.md 中获取 (x2),然后移入 AGENTS.md(针对 Agent 的规则)、检查脚本(如果可以自动化)或提示词模板。
  • 发现规则。 每个发现都在同一次会话中进入仓库文档,标记为已确认、未验证或错误,并附有证据。修复后来发现是错误的旧声明。保持行尾符。
  • 安全发布。 不要提交任何受版权保护或个人内容:pre-commit 钩子和 CI 运行 check-safe-to-publish.py。用户提供他们自己的游戏文件。

会话移交

将此与 project-handoff 技能配对使用。在每次审查轮次结束时或当上下文变得庞大时,建议进行移交。切换例程:

  1. Claude 更新 docs/HANDOFF.md,运行 check-handoff.py,然后提交。
  2. 用户运行 Claude 要求的任何操作(日志、捕获)。
  3. 用户将提示词交给 Agent。
  4. 新的 Claude 聊天:粘贴 HANDOFF.md(或者,如果聊天可以读取仓库,则“读取 docs/HANDOFF.md 并执行其首要做的事”)。Agent 的报告已经在它自己的分支上,因此无需粘贴其他内容。

相关技能