agency-agents 多 Agent 花名册
它本质上是一批 markdown 文件——每个 agent 一个文件，
带 YAML frontmatter 和写给模型的提示词正文，再由仓库自己的脚本渲染成
Claude Code、Cursor、Codex、Gemini CLI 等 16 种工具各自认识的格式。
不是框架，没有运行时，也没有任何代码在强制执行它那套编排流程。
本专题共 40 篇，回答四件事：
这个字段到底管什么、装到哪去了、报错了怎么判定、该不该用。
内容依据
官方仓库
的 README、tools.json、divisions.json 与 scripts/ 下的安装与校验脚本整理，
核对日 2026-08-09。本专题内容为仓库源码与文档口径，我们没有安装或运行过其中任何 agent；
目录与路径随上游更新而变动，请以仓库最新内容与 ./scripts/install.sh --help 的实际输出为准。
agency-agents 到底是什么：255 个 agent 的目录，不是一个框架
agency-agents 常被当成一套多智能体框架，实际上它是 255 个带 YAML frontmatter 的 agent markdown 文件加一组 shell 脚本组成的目录，本身没有运行时。本文按仓库源码口径讲清单个 agent 文件的三层结构、17 个 division 的划分规则、哪些顶层目录根本不是 division、convert 与 install 两步流水线，以及 per-agent、roster、plugin 三种安装形态的差别，帮你判断这个仓库要不要进自己的工作流、又该怎么收窄安装范围。
机制与文件格式
agent markdown 的三层结构、必填与可选字段、章节标题为什么会决定转换产物的去向、17 个 division 与那四个「不是 division」的目录、单一真相源怎么落地、原创性检查用什么算法挡住「换个国家名的换皮 agent」。
17 个 division 与那四个「不是 division」的目录
agency-agents 仓库根目录下摊着二十来个文件夹，但只有 17 个算 division，另外四个是转换产物、方法论文档、示例和脚本。这篇讲清楚 divisions.json 与 check-divisions.sh 认定 division 的机械标准是什么、255 个 agent 在 17 个 division 里怎么分布得极不均匀、为什么按目录整体拷贝在 engineering 这种大 division 上是钝器，以及要按题材找 agent 时该回哪份文件查，而不是照着目录名猜。
给 agent 章节起标题其实是在写路由：agency-agents 的 SOUL.md / AGENTS.md 分流机制
在 agency-agents 里，agent markdown 的二级标题决定这段正文被转换到 OpenClaw 工作区的 SOUL.md 还是 AGENTS.md。本文按 lint-agents.sh 的 classify_header_target() 源码讲清六个命中关键词、默认落点，以及自己写 agent 时该怎么定标题。
换个国家名就想混过去？8 词 shingle 重叠率不答应
把已有 agent 换个国家名或平台名提交上来，评审几乎看不出来。agency-agents 的 check-agent-originality.sh 用实体中性化后的 8 词 shingle 重叠率来抓这种换皮，默认 40 判失败、20 出警告，而源码注释给出的库内校准值是最差约 1.5%、中位数 0%。这篇拆开这套机制的判断依据：三组数字放在一起该怎么读、指定文件与全库审计两种模式分别用在哪、退出码 1 和 2 为什么必须分清，以及它和 lint 加起来仍然管不到的那部分。
同名 format 保证字节级相同输出：一条被写进注释的契约
agency-agents 的 tools.json 用 _note 写死一条约定：同一 format 名必须渲染出字节级相同的输出。本文拆开 format 与 installKind 两个正交维度，说明 Claude Code 与 GitHub Copilot 为何共用 identity，排查转换问题时该查几份内容。
一份 JSON 管住五个脚本：单一真相源是怎么落地的
agency-agents 用 divisions.json 与 tools.json 当作目录和工具的唯一真相源，再用五个校验脚本把不一致直接变成构建失败。本文拆开这套机制：五个脚本各守什么、为什么原创性检查要去读 JSON 而不是在脚本里硬编码一份拷贝、installKind 与 format 这类契约字段为什么必须写进 JSON，以及新增一个 division 时官方给的四步顺序。给的是判断依据，你可以照着评估自己仓库里的配置有没有真正收敛。
一个 agent 文件长什么样：frontmatter、角色声明、分节正文
agency-agents 仓库里的 agent 全是同一套 markdown 模板，三层结构固定，看懂一个等于看懂两百多个。这篇按仓库校验脚本的源码讲清楚 frontmatter 必填哪三个字段、哪些只是可选、正文为什么要写成第二人称，以及最反直觉的一条：你给章节起的标题不只是排版，它决定这段内容被转换进 SOUL.md 还是 AGENTS.md，写模板之前就得照着这条路由规则起名，否则落点全错。
agency-agents 的 agent 文件格式：name/description/color 是必填，emoji/vibe 不是
写或改一个 agency-agents 的 agent markdown，到底哪几个 frontmatter 字段是硬要求？本文从仓库 lint 脚本的必填字段列表出发，讲清 name、description、color 这三项为什么是 ERROR 级，emoji 与 vibe 为什么只是可选，字段值又分别被哪些转换器消费，顺带说明为什么你给正文起的章节标题其实是一条路由规则，原创性检查的两个默认阈值该怎么读，以及这套检查脚本管得到什么、管不到什么。
per-agent、roster、plugin：三种安装机制决定了你能不能只装一个
agency-agents 的 tools.json 给 16 种工具各标了一个 installKind，它决定的不是装到哪，而是产物形态：per-agent 一 agent 一文件，roster 合并成一个文件，plugin 只能走命令行。本文讲清三者的判断依据、format 的字节级契约，以及家目录与当前目录的落点差异。
安装与格式转换
16 种工具、16 个落点，从 convert.sh 渲染到 install.sh 落盘的完整链路。四个选择器怎么组合、符号链接模式的取舍、12 个环境变量改到哪、Windows 上的门槛在哪。
`--link` 符号链接模式：改动自动传播的好处与代价
agency-agents 的 install.sh 提供了 --link 开关，用符号链接代替拷贝，改动会自动传播。本文按仓库源码口径讲清它在 convert → install 这条链路的哪一段生效、命令该怎么组合、三种 installKind 下产出物形态有什么差别、装完要检查哪几处，以及哪些场景不该用它。
`--parallel` 与 `--jobs`：多工具安装的并行控制
agency-agents 的 install.sh 提供了 --parallel 与 --jobs 两个开关，用来同时往多个 AI 编码工具的配置目录里铺 agent 文件。这篇从并行到底并行的是什么讲起，给出可直接复制的命令组合、产出物会落在哪些目录、装完人工要检查哪几处，以及哪几种情况下并行反而会让你更难定位问题、不如老老实实串行跑一遍。
12 个环境变量：不想装进默认目录时改哪里
agency-agents 的 install.sh 默认写进 ~/.claude/agents/ 这类家目录，而 opencode、Cursor、Aider、Windsurf 写的是当前目录。本文梳理 12 个可覆盖落点的环境变量各管哪些工具、剩下 5 个只能靠 --path，以及怎么先 --dry-run 看计划。
16 种工具、16 个落点：一张表搞清装到哪去了
agency-agents 的 16 种工具各有各的落点，有的写进家目录，有的写进当前项目目录，有的把整份花名册合并成一个文件，还有一个压根不能按 agent 渲染。这篇把 tools.json 与 install.sh 注释里的落点整理成一张表，讲清 per-agent、roster、plugin 三种安装机制的区别，并给出先 dry-run 再落盘的完整命令写法、装完要检查哪几处、以及哪些场景不该整包装。文中事实均以 2026-08-09 的仓库源码与脚本注释口径为准。
把 agency-agents 装进 Claude Code：从 convert 到 install 的完整链路
agency-agents 进 Claude Code 只有两段：convert.sh 渲染产物，install.sh 拷进 .claude/agents。按脚本 USAGE 与 tools.json 契约讲清选择器、--dry-run、--link 怎么组合，Windows 走 Git Bash 还是 WSL，落盘后验收看哪三处。
往 `~/.claude/agents/` 写 200 多个文件之前，先跑 `--dry-run`
agency-agents 花名册有 255 个 agent、17 个 division，安装脚本支持 16 种工具，多数是一个 agent 一个文件；裸调用 install.sh 等于全装。这篇讲 --dry-run 的命令怎么写、每个选项为什么在那里、计划打出来后人要盯哪几处、哪些场景它兜不住底。
agency-agents 安装选择器实战：--tool/--division/--agent/--agents-file 怎么组合
agency-agents 的 install.sh 裸调用会把整个花名册装进所有检测到的工具，多数人并不想要这个结果。这篇按官方 USAGE 段的参数语义，拆开 --tool、--division、--agent、--agents-file 四个选择器各自管什么，给出四种常见处境下可直接复制的完整命令，说明产出物会落在哪些目录、怎么用 --dry-run 和 --list 验收，以及 roster、plugin 两类工具为什么在目标端看不到一 agent 一份产物。
Codex 的 TOML 转换：为什么正文要走 basic string
agency-agents 把 agent markdown 转成 Codex 能读的 TOML 时，只写 name、description、developer_instructions 三个字段，而正文一定要经过 TOML basic string 编码。本文按仓库源码讲清这条链路怎么跑：完整命令与每个选项的作用、产物落在哪个目录、装完人要检查哪几处、以及哪些场景根本不该这么装。
Windows 上怎么装：Git Bash、WSL 与 bash 3.2 的门槛
agency-agents 是一套 shell 脚本驱动的 agent 分发工具，Windows 用户第一步就会卡在「用什么终端跑」这个问题上。这篇按仓库脚本注释与 tools.json 的原文，梳理 Git Bash 与 WSL 到底该选哪个、判断依据为什么是安装落点、bash 3.2 这条版本下限怎么自查、先用 dry-run 看计划再落盘的完整命令该怎么写、行尾换行符这个 Windows 专属的坑，以及装完之后人要检查哪几处、什么情况下压根不该这么装。
排查
Cursor 里装完像没装、开头明明是三个横杠却报 missing frontmatter、CI 校验脚本失败时该同步改哪几处——按脚本源码语义给判定方法，并说清什么情况说明不是这个原因。
`check-divisions.sh` 失败：四个地方要同步改
在 agency-agents 里新增或改名一个 division 目录后，check-divisions.sh 会让构建失败。这篇按「现象→判定→处置→验证→排除」五步走一遍：先确认失败是否真的来自 division 列表漂移，再照 divisions.json 里 _note 给的顺序把磁盘目录、convert.sh、lint-agents.sh、CI 工作流四处对齐，最后给出哪些报错其实归其它脚本管。
`check-tools.sh` 失败：加一个工具要动三处
agency-agents 仓库里给花名册新增一种目标工具时，最容易挂在 check-tools.sh 这道校验上。这篇按「现象→判定→处置→验证→排除」五步拆开：这个脚本到底守 tools.json 与 install.sh、convert.sh 之间的哪些一致性，六个必填字段各是什么含义，format 的字节级契约和三种 installKind 怎么选，以及哪些失败其实归 lint-agents.sh、check-divisions.sh 管，不该往这里找原因。
255 个 agent 全装进全局目录，代价是什么
裸跑 agency-agents 的 install.sh，按脚本 USAGE 的说法就是把所有 team 装到所有检测到的工具，而仓库里带 frontmatter 的 agent 共有 255 个。本文按排查顺序讲清楚：怎么用 --dry-run 和 --list 在落盘前确认产物数量与目标目录，怎么按 tools.json 里的 installKind 判断产物形态，怎么用选择器把安装范围收窄，以及哪些症状其实和装多装少完全无关。
明明开头就是三个横杠，为什么报 missing frontmatter
在 agency-agents 里写或改一个 agent markdown，文件第一行明明就是三个横杠，校验却说 frontmatter 不存在。本文按现象、怎么确认、源码语义给出的处置、处置后怎么验证、什么情况不是这个原因五步，讲清 CRLF 行尾引起的误导性报错，给出可执行的单文件校验判定动作，并列出同样指向 frontmatter 却与行尾无关的几种根因，帮 Windows 侧读者少绕弯路。
agency-agents 排查：body seems very short，50 词这条线是怎么来的
agency-agents 的 lint-agents.sh 会对正文不足 50 词的 agent markdown 报一条 body seems very short 警告，可你的文件明明写了好几屏。这篇讲清这条线出自脚本第 4 步的取正文与词数统计，给出可执行的判定动作与处置，并说明它为何常与另外几条 WARN 结伴。
Cursor 里装完没反应？看一眼 `alwaysApply: false`
把 agency-agents 装进 Cursor 后规则像没生效，多半不是脚本失败，而是 convert.sh 的 cursor-mdc 模板把 alwaysApply 写死为 false、globs 写死为空串。本文按现象、判定动作、源码语义、验证、排除五步给出排查路径，并列出五种说明另有原因的情况。
integrations/ 缺失或过期时到底发生了什么
agency-agents 的 integrations/ 是 convert.sh 写出的产物目录而不是源目录。本文梳理产物缺失或过期的表象、用 --dry-run 与 --list 不落盘确认的办法、脚本给出的处置与复核方式，以及哪些其实是 installKind、目录 scope 或 CRLF 导致的另一类问题。
lint 报了一屏：哪些必须修，哪些可以先放着
写完一个 agency-agents 的 agent markdown，跑一遍仓库自带的 lint 脚本，输出里 ERROR 和 WARN 常常混在一起，让人不知道该先动哪一条、哪一条可以留到下次。这篇按 scripts/lint-agents.sh 的源码把五道检查逐条拆成阻塞项和建议项，指出其中哪一条 WARN 会直接影响转换产物的分流、应当按硬伤处理，并给出修完之后还要补跑哪几个一致性脚本，以及哪些症状其实跟校验完全无关、不该在这里浪费时间。
runbook 里的 slug 解析不到 agent 文件时怎么查
agency-agents 的 runbook 用 slug 引用 agent，而 slug 是 agent markdown 的文件名主干，既不等于显示名，也不保证带 division 前缀。本文按现象、判定动作、源码语义给出的处置、处置后怎么验证、什么情况说明不是这个原因五步，讲清 slug 解析不到文件时该从哪里下手，并列出几种看着像 slug 写错、实际是安装形态或目录 scope 造成的情形。
NEXUS 多 Agent 编排
NEXUS 是写在 markdown 里的编排方法论，不是调度器。三种模式、七个阶段、四个可直接照搬的场景 runbook，以及「每个阶段之间都有质量门、所有评估都要有证据」这条贯穿设计。
交接文档、QA 失败反馈、升级报告：三个模板的用法
agency-agents 的 NEXUS 编排文档里放了三个协同模板——交接文档、QA 失败反馈、升级报告。这篇讲清楚它们分别在哪个环节触发、怎么落到自己的项目目录里、为什么必须写 agent 的 slug 而不是显示名，以及怎么做一次可执行的验收检查；同时说明它们不会被安装脚本装进任何工具，也没有代码会强制执行。
每个阶段之间都有质量门，所有评估都要有证据
agency-agents 的 NEXUS 激活提示词末尾有两句约束——阶段之间设质量门、所有评估都要有证据。这两句在仓库里分成两层落点：一层写在 markdown 方法论里靠模型自觉，另一层是 shell 脚本，跑起来真会让检查失败。本文拆开两层各自守什么，并给出判断依据：哪些门该写成脚本，哪些只能写成清单。
那段激活提示词逐句拆解：它到底在要求模型做什么
agency-agents 的 QUICKSTART.md 里给了一段 NEXUS-Full 激活提示词，很多人整段复制粘贴却说不清它在要求模型做什么。本文把这段提示词按行拆开，逐句对上仓库里的模式定义、七个阶段 playbook 与花名册 slug，给出激活前的准备命令、四个可执行的验收动作，以及哪些场景根本不该用这一段。
事故响应 runbook：为什么「修完」之后还有一组人
agency-agents 的 runbooks.json 里，只有 incident-response 走 NEXUS-Micro。它最值得看的是修完之后还单独挂着一组 post-fix agent：取证、接口回测、流程优化、重排优先级。本文讲这份名单怎么落到 install.sh 参数里、装完验收哪几处。
为什么 runbook 引用 slug 而不是显示名
agency-agents 的 runbooks.json 里，一个团队是由 engineering-frontend-developer 这样的 slug 拼出来的，而不是花名册里显示的 Frontend Developer。这篇讲清楚 slug 到底指什么、为什么显示名当不了引用键、check-runbooks.sh 守的是哪条边界，并用花名册里五组 slug 与显示名的真实对照说明这层映射为什么推不出来，最后给出一套判断标准：你自己项目里的跨文件引用，什么时候该写稳定 id，什么时候可以直接写名字。
Full、Sprint、Micro：三种模式各自适合什么活
agency-agents 的 NEXUS 给了 Full、Sprint、Micro 三种激活模式。这篇不复述文档表格，而是从交付物形态、官方四个 runbook 的模式归属、roster 的分组激活结构三个角度，给出能自己套用的判断依据：什么时候往上走一档，什么时候往下退一档，以及为什么大多数活落不到 Full。
NEXUS 是什么：写在 markdown 里的多 agent 编排方法论
agency-agents 的 strategy/ 目录里没有一个可安装的 agent，放的是一套叫 NEXUS 的多 agent 编排方法论。本文讲清它的全称、三种激活模式、七个阶段与四个场景 runbook 各自对应仓库里的哪些文件，以及它靠什么生效、又约束不了你什么。
Phase 0 到 Phase 6：七个阶段的分工与产出
agency-agents 仓库的 strategy 目录里放着一套叫 NEXUS 的多 agent 编排方法论，把项目拆成 Phase 0 到 Phase 6 七个阶段，每个阶段有对应的 playbook 文档和参与角色。这篇按官方文档口径拆解七个阶段各自的分工、进场角色、交接契约与质量门设计，说清它是写在 markdown 里的方法论而非可执行调度器，并给出三种激活模式的选择依据，帮你判断自己的项目该保留哪几个阶段、哪几个可以直接砍掉。
Startup MVP runbook：9 个常驻 agent 加两组按需
agency-agents 的 startup-mvp runbook 把一个 MVP 团队写成 18 个 slug：9 个常驻、3 个第三周起加入、6 个按需。本文把这份名单落成 agents-file，给出 install.sh 的完整命令、--dry-run 的用法、产出物落点与验收要点，以及什么情况下别照它装。
选型与自建
该不该用、按角色选哪几个 division、用现成的还是照它的规范自己写——给决策路径，不罗列参数。
按你的角色选 division：agency-agents 不用一次全装
agency-agents 有 255 个 agent、17 个 division，裸调用 install.sh 就是全装到所有检测到的工具。这篇给一条决策路径：先看工具属于哪种 installKind，再看它落在家目录还是当前项目，最后才谈按角色挑哪几个 division，并附 --dry-run 用法与 Cursor 转换产物写死 alwaysApply 的坑。
用现成的 agent 还是自己写：一个务实的判断路径
面对 agency-agents 这样一个有 255 个 agent、17 个 division 的花名册，很多人第一反应是装上再说。这篇不罗列参数，而是从你自己的处境倒推：任务能否在花名册里找到对口的、名字对口是否等于内容对口、哪三种信号说明只能自己写、自己写一份的真实成本，以及哪些维度我们没有依据、干脆不比。
照它的规范写自己的 agent：五道检查逐条对齐
想往 agency-agents 的规范里加一个自己的 agent，动手前有五个选择要先做：这个 agent 值不值得新写、放进哪个 division、frontmatter 填几个字段、章节标题怎么起、正文写多长。这篇不罗列字段表，而是按仓库里 lint-agents.sh 与 check-agent-originality.sh 的实际语义，把每个选择的判断依据和对应的检查等级讲清楚，没依据的地方直接说不比。
这套东西该不该用：先问自己四个问题
agency-agents 是一批 markdown 提示词加一套安装脚本，装不装得进你的工具、能不能只装一部分、装在家目录还是项目目录、它的质量门到底管什么，这四件事决定了它适不适合你。本文按仓库源码与文档口径，把选型拆成一条可以自己走完的决策路径，不做效果评价。
想把多个 Agent 真正编排起来，而不只是复制提示词？
从 AI 编程实践到 Agent 工程落地，站内有成体系的教程与课程。