Agency Agents（msitarzewski/agency-agents）：把「282 个专业角色」编译成 17 种智能体原生格式——一个 15.7 万星角色库的工程化拆解

一、导读

Agency Agents 是一套把 AI 编程智能体变成「AI 代理机构」的角色库：282 个带完整人格、工作流与交付物的专家 Agent，覆盖 18 个部门（Engineering 65 个、Specialized 59 个、Marketing 37 个……）。它的关键结论不是「又收集了一堆提示词」，而是用一层「格式契约 + 转换器 + 安装器 + CI 门禁」把同一份源文件编译到 17 种宿主的原生格式——MIT 协议、★157,389、当日涨星 +744，且无需改动代码即可在 Claude Code、Codex、Cursor、Gemini CLI 之间平移。

二、项目速览

项目	详情
仓库	msitarzewski/agency-agents（GitHub API，数据获取日 2026-10-05）
作者	Mark Sitarzewski（msitarzewski）
主语言	Shell（转换器/安装器/校验器均为 Bash，另有 Python 插件构建脚本）
Star 总数	157,389；当日涨星 +744（GitHub Trending daily，2026-10-05 抓取）
Fork / Watch	25,383 / 1,132
License	MIT
首次发布	2025-10-13（仓库创建）
最新提交	2026-10-04（单日合并 49 个 PR，#968–#1026）
规模	282 个 Agent（18 个 division）· 432 个文件 · README 84,778 字符
支持宿主	17 种（以 tools.json 为准）
发布形态	源码仓库 + 独立桌面 App（agencyagents.app）

三、为什么是它：问题背景与定位

痛点：智能体时代的「角色」是碎片化的。 每个宿主都有自己的 Agent 定义格式——Claude Code 读 .claude/agents/*.md 加 YAML frontmatter，Codex 要 .codex/agents/*.toml，Cursor 要 .cursor/rules/*.mdc，Aider 与 Windsurf 更极端，只认单文件（CONVENTIONS.md／.windsurfrules）。于是任何想跨工具复用的角色库都面临一道隐形成本：为 N 个宿主维护 N 份内容几乎相同、格式各异的副本，而副本一旦漂移，就再也无法证明它们表达的是同一个角色。

定位：一个「源 → 多目标」的编译式角色库。 项目把 Agent 定义收敛为一份带 frontmatter 的 Markdown 源文件，再通过 convert.sh 编译到各宿主原生格式、通过 install.sh 落到目标目录。作者的原话是：The Agency 与 Claude Code 原生协作，同时提供转换与安装脚本，让同一批 Agent 能用在所有主流 agentic 编码工具上。

涨星动因拆解。 一是零门槛触达——一行 ./scripts/install.sh --tool claude-code 就能把整支「团队」装进本地，30 秒见效，是纯粹的即时满足；二是**「代理机构」叙事自带传播性**——把 282 个角色拟人化（每个都有 vibe、emoji、颜色、成功指标），比抽象框架更容易被转述；三是跨工具中立——在宿主混战的当下它不站队，反而是最大的公约数；四是工程纪律撑住了信任——6 个 CI 工作流把「格式是否正确」变成可强制执行的构建门禁；五是生态外溢——桌面 App、brew cask 与多语言社区评测共同放大曝光。

四、【重点】架构原理

4.1 整体架构：一源多目标的编译流水线

┌── 源层（唯一事实）────────────────────────────────────────────┐
│ engineering/*.md · design/*.md · marketing/*.md …（282 个）  │
│ 每个文件：YAML frontmatter（name/description/color/emoji/    │
│          vibe）+ 人格、使命、硬规则、交付模板、成功指标        │
│ divisions.json（部门集合·图标·品牌色）                        │
│ tools.json（工具集合·安装契约·渲染格式）                       │
└──────────────┬───────────────────────────────────────────────┘
               │ ① scripts/convert.sh（编译：源 → 目标格式，只写字）
               │    按 format 渲染：identity / codex-toml /
               │    gemini-md / cursor-mdc / aider-conventions /
               │    windsurf-rules / skill-md / hermes-router-plugin
               ▼
┌── 生成物层（integrations/，非源、非部门）─────────────────────┐
│ integrations/claude-code/ · codex/ · cursor/ · gemini-cli/   │
│ aider/ · windsurf/ · opencode/ · hermes/ · openclaw/ · …     │
│ 注意：此目录被 check-divisions.sh 通过 NON_DIVISION_DIRS 排除 │
└──────────────┬───────────────────────────────────────────────┘
               │ ② scripts/install.sh（投递：目标格式 → 用户机器）
               │    自动探测已装工具；确认目的地与作用域
               │    （user 级 vs project 级）；拒绝覆盖用户自有文件
               ▼
┌── 宿主层（17 种智能体，各读原生格式）─────────────────────────┐
│ Claude Code  ~/.claude/agents/{slug}.md                     │
│ Codex        ~/.codex/agents/{slug}.toml                    │
│ Cursor       .cursor/rules/{slug}.mdc（项目级）              │
│ Aider        CONVENTIONS.md（全 roster 单文件）              │
│ Windsurf     .windsurfrules（全 roster 单文件）              │
│ Hermes       ~/.hermes/plugins/agency-agents-router（插件）  │
└──────────────┬───────────────────────────────────────────────┘
               │ ③ 运行时协作（三种，可叠加）
               ▼
┌── 协作层 ─────────────────────────────────────────────────────┐
│ 人工串场：Activate <Role>，你负责粘贴交接物                   │
│ 记忆化：MCP memory（remember/recall/rollback/search）        │
│         Agent 按 tag 自动召回上一环节的交付物                  │
│ 编排层：strategy/ NEXUS 六阶段 playbook + 四类 runbook        │
└──────────────┬───────────────────────────────────────────────┘
               │ ④ 质量门禁（6 个 CI 工作流，合并前强制）
               ▼
┌── 校验层 ─────────────────────────────────────────────────────┐
│ lint-agents.yml      → 282 个 agent 结构/颜色/fence 校验      │
│ check-divisions.yml  → divisions.json 与目录、脚本数组一致    │
│ check-tools.yml      → tools.json 与 install/convert 一致     │
│ check-runbooks.yml · check-hermes-config-rewrite.yml          │
│ test-install.yml     → 安装路径端到端                          │
└───────────────────────────────────────────────────────────────┘

4.2 分层模块拆解

层	职责与关键接口
源层	一个 Agent 一个 Markdown 文件，frontmatter 承载机器可读元数据（name/description/color/emoji/vibe），正文承载人格与流程；文件名即 slug 来源
元数据层	divisions.json 声明部门集合（label/Lucide 图标/品牌色）并明确「并非每个顶层目录都是部门」；tools.json 声明 17 种工具的安装契约（id/探测目录/目标模板/format/installKind/作用域/版本命令）
编译层	scripts/convert.sh，30,738 字节的 Bash，按 --tool 渲染；format 名相同即保证字节级一致输出；--parallel/--jobs N 并行；从不触碰用户配置目录
投递层	scripts/install.sh，自动探测已装工具、--tool/--division/--agent/--agents-file 四级筛选、--link 符号链接、--dry-run、--parallel；不覆盖用户自有文件，跳过项记入 SKIPPED_LOG
校验层	scripts/lint-agents.sh 与 5 个 check-*.sh；校验的是结构而非文采：frontmatter 三字段、CRLF、折叠 YAML、颜色可解析、代码围栏闭合与嵌套
集成层	integrations/<tool>/ 为纯生成物；integrations/mcp-memory/ 是唯一的「能力集成」而非格式转换
编排层	strategy/ 的 NEXUS 战略（phase-0 发现 → phase-6 运营）、coordination/ 交接模板、runbooks/ 四个场景手册
分发层	Git 仓库 + agencyagents.app 桌面应用（独立仓库 agency-agents-app）+ brew cask

4.3 核心机制与算法原理

① 格式契约：同一 format 名 ⇒ 字节级一致的输出。 这是全项目最关键的一条设计约束。tools.json 写得很硬：「同一个 format 名保证输出逐字节相同，所以两个工具可以共用一个 format，当且仅当它们渲染出的文件完全一致」。这条契约解决了一个隐蔽的正确性问题——如果两个宿主格式「看起来差不多」，各自维护一份渲染逻辑，迟早会漂移；而用一个共享的 format 名把「等价」变成可断言的机器事实，漂移就无处藏身。与之并列的还有 installKind，它是上游真相：per-agent（每 agent 一个文件或目录）、roster（全部 agent 合成一个文件）、plugin（构建产物，无法按 agent 渲染）。消费者必须同时按这两个维度分支——Aider 与 Windsurf 是 roster，Hermes 是 plugin，其余多为 per-agent。

② 两段式流水线：编译与投递严格分离。 convert.sh 只写 integrations/，从不触碰用户配置目录；install.sh 只负责把已编译产物投递到目标路径。这一刀切得干净：转换可重复、可 diff、可进 CI，而投递涉及用户文件系统、可能失败、必须可回滚。install.sh 在产物缺失或过期时会自动补跑 convert.sh，但对 claude-code 与 copilot 例外——这两个宿主用源文件本身，无需转换。

③ 幂等与「不越界」的投递纪律。 install.sh 明确拒绝覆盖用户自有文件、拒绝替换指向外部的符号链接，只刷新「安装器自己拥有的链接」，所有跳过都进 SKIPPED_LOG 并在结尾汇总成盒框报告。Hermes 安装器声明只删除自己的插件目录，更新 config.yaml 时修复旧缩进与损坏项且保持幂等；OpenClaw 安装器在无法确认注册状态时拒绝猜测。这些细节指向同一条原则：一个会被反复执行的安装器，最大风险不是装不上，而是装坏了别人的东西。

④ 颜色名必须可解析——一次真实的静默失败。 lint-agents.sh 里有一段注释值得单独拎出：颜色检查最早只校验字段存在，结果有四个 agent 写了一个没有任何映射知道的颜色名，在 OpenCode 集成里静默渲染成灰色，「四处无人告警」；更具体的细节是 slate 与 navy 两个名字跨四个 agent 一直没被发现。修复方式不是硬编码一份颜色表（那会漂移），而是从 convert.sh 的 resolve_opencode_color() 函数里 awk 出真实已知的颜色名——让校验器读取干活的那份真相。这是教科书式的「校验器不应复制被测对象的知识」。

⑤ 围栏嵌套：Markdown 里没有嵌套。 lint-agents.sh 最精巧的一段是代码围栏状态机：逐行跟踪 fence_marker/fence_len/fence_indent，用 fence_closes_p 与 fence_open_p 判定开闭。规则来自 CommonMark 与 GitHub 的真实行为——等长围栏无法嵌套。若某模板在四反引号 markdown 块里再写三反引号 bash，GitHub 会把内层围栏行当作普通文本，并在下一个裸三反引号处结束外层块，导致模板剩余部分整体渲染成文档正文。校验器对此直接报 ERROR 并给出修法：把外层围栏加长一行（用四个反引号包住）。它还处理了 grep -q 提前退出使 pipefail 把 SIGPIPE 的 141 误判成「无匹配」的竞态，以及 macOS/BSD 上 wc -w 的前导空白问题。

⑥ 校验器读取的「两类 Markdown」。 同一个 lint 还要判断 Agent 文件有哪些 ## 级标题，并按 classify_header_target() 把标题归类为 soul（Identity、Learning & Memory、Communication、Style、Critical Rules）或 agents（其余）。这两类分别对应 convert.sh 里 SOUL.md 与 AGENTS.md 两个输出目标——OpenClaw 工作区同时要 SOUL.md 与 AGENTS.md。若两类标题各自为零，就各发一条 WARN。这把「人格」与「能力」在结构层面显式分开，也解释了为什么 Agent 文件里那些文学化的标题其实是有机器含义的契约。

⑦ 记忆化协作：用 MCP 取代人手粘贴。 integrations/mcp-memory/ 给出的不是格式转换，而是协作模式。默认流程里，每次 Agent 交接都是「你粘贴上一环的输出」——你才是胶水，而会话超时、多 Agent 缺上下文、QA 失败要回滚、项目跨天跨周这四种情况会直接击穿它。引入任一支持 remember/recall/rollback/search 的 MCP 记忆服务后，交接退化为一句「Project: RetroBoard. Recall previous context for this project」。三条关键模式是：所有记忆都打项目名 tag；交付物额外打「接收方 Agent 名」tag，让下游一召即得；rollback 取代手工撤销——文档直接把 rollback 称作 killer feature。

⑧ 三档强度：从 30 秒试用到组织级编排。 轻档是「激活一个角色」——Activate Frontend Developer；中档给 Agent 加 Memory Integration 段落，用记忆打通交接；重档是 strategy/ 的 NEXUS：phase-0 发现到 phase-6 运营的六阶段 playbook，加上四个 runbook（企业级特性、事件响应、营销活动、创业 MVP）与 coordination/ 交接模板。同一批 282 个角色，可以只用其中一个，也可以当成一支完整公司的编制来用。

4.4 性能优化手段与设计取舍

取舍	为什么这么做	代价
用 Shell 写转换器与安装器	无运行时依赖，Linux/macOS/Windows Git Bash 通吃	需自建 Bash TUI 向导；处理 BSD/GNU 差异
一个 Agent 一个 Markdown 文件	可直接被宿主读走，也可被人读懂	部门切分需靠 divisions.json 与 CI 维持一致
format 名绑定字节级一致	把「两种格式等价」变成可断言的机器事实	两个几乎相同的格式不能各自微调，只能共享或明确分叉
installKind 作为上游真相	让 App 与 CLI 都按同一契约分支	plugin 类工具只能走 CLI，App 无法渲染
安装器拒绝覆盖用户文件	反复执行安全，避免破坏用户资产	已有同名文件会被跳过而非更新，需查 SKIPPED_LOG
校验结构而非内容质量	可自动化、可强制、不引入主观判断	无法判断一个 Agent 的提示词写得好不好
记忆能力外挂给 MCP	不绑定具体记忆实现，任何满足四工具的服务器都可用	必须用户自行配置；记忆质量取决于 tag 纪律
面向 17 种宿主而非绑定一家	在宿主混战中保持中立，扩大适用面	各宿主的目录、作用域、容量上限差异都要单独处理

4.5 与其他架构路线的差异

与「单宿主 Agent 集合」：多数角色库直接面向 .claude/agents/。Agency 的差异在于把源与目标解耦，多出编译与校验两段，换来跨工具平移能力。

与「Agent 技能包」路线：技能包通常以技能目录 + SKILL.md 为单位、面向任务流程；Agency 的单位是角色（谁在做），强调人格、硬规则与交付模板。二者互补：技能回答「怎么做」，角色回答「谁来做、按什么标准交付」。

与「多智能体编排框架」：编排框架在运行时接管调度与消息传递；Agency 在编排层是声明式的（NEXUS playbook + 交接模板 + 可选 MCP 记忆），执行仍交给宿主。代价是确定性与可观测性更弱，收益是零侵入。

与「提示词市场」：市场以分发为中心、质量靠评分；Agency 把质量前移到 CI 门禁——格式错了直接构建失败，而不是等你踩坑后打低分。

五、【重点】应用场景

场景一：单人做完整 MVP，用「现实检查员」设卡

业务痛点：一个人推进 MVP 时，最难的不是写不出代码，而是没人拦你——需求没验证就开工，进度乐观到最后一周崩盘。 如何解决：把交付链拆成若干角色，并用 Reality Checker 在每个里程碑做 GO/NO-GO 裁决，且要求每一条结论附证据。

./scripts/install.sh --tool claude-code --division product,engineering,testing
# 在 Claude Code 中按阶段激活：
# Activate Sprint Prioritizer. → 产出 4 周冲刺计划
# Activate UX Researcher.      → 产出竞品分析与差异点
# Activate Reality Checker.    → "Recall all deliverables. Can we ship in 2 weeks?"

仓库示例 examples/workflow-startup-mvp.md 给出一条完整时间线（RetroBoard，4 周，单人，React + Node）。 收益与量化：示例工作流把「4 周 MVP」拆为可验收的 4 个冲刺，并给出各角色成功指标（如前端角色的基线是 Lighthouse 性能与无障碍持续 > 90、3G 下加载 < 3 秒、组件复用率 > 80%——这些数字写在 engineering-frontend-developer.md 的 Success Metrics 里，可直接当验收口径）。 适用边界：这是流程脚手架，不是质量保证。Agent 的成功指标是提示词里的自我约束，没有任何机制去实测 Lighthouse 分数；不建议在没有人工复核关键决策的合规场景直接采信。

场景二：一份源，装到 17 种宿主（团队混用工具时）

业务痛点：团队里有人用 Claude Code、有人用 Cursor、有人被规范要求用 Qwen Code，同一套团队约定在每个工具里都要重写一遍，且必然会漂移。 如何解决：只维护源层 Markdown，用转换器生成各宿主格式，再用安装器投递。

# 只装指定部门，投递到当前项目（Cursor 是项目级）
./scripts/install.sh --tool cursor --division engineering,security

# 先看计划再执行
./scripts/install.sh --tool codex,gemini-cli --dry-run

# 只装某几个角色；用符号链接便于随仓库更新
./scripts/install.sh --tool claude-code --agent frontend-developer,reality-checker --link

# 并行安装到多个工具
./scripts/install.sh --no-interactive --parallel --jobs 8

收益与量化：tools.json 给出 17 个目标的确定路径与作用域（Claude Code 为 .claude/agents/{slug}.md 且 user/project 双作用域，Cursor 仅项目级 .cursor/rules/{slug}.mdc，Aider/Windsurf 为单文件 roster）。收益是「源改一次，全部目标同步」，且因为 format 名绑定字节一致，可以断言两个共享 format 的宿主拿到的是同一份内容。 适用边界：opencode 有约 119 个 agent 的注册上限，超出会告警——而本项目有 282 个，因此直接全量装到 opencode 不可行，必须先按 --division 或 --agent 收敛。此外 plugin 类工具（Hermes）不提供聚合 roster，只能通过 CLI 安装。

场景三：用 MCP 记忆消灭「人工胶水」

业务痛点：多角色协作最耗人的环节是在角色之间搬运上下文——粘贴 sprint 计划、粘贴 API 设计，QA 打回时还要描述「哪里错了、回到哪个版本」。 如何解决：接入任一实现 remember/recall/rollback/search 的 MCP 记忆服务器，并给常用 Agent 加上 Memory Integration 段落。

{ "mcpServers": { "memory": { "command": "your-mcp-memory-server", "args": [] } } }

Activate Backend Architect.
Project: RetroBoard. Recall the sprint plan and research brief from previous agents.
Design: 1) database schema 2) REST endpoints 3) WS events 4) auth strategy.
Remember each deliverable tagged for this project and for the frontend-developer.

收益与量化：examples/workflow-with-memory.md 用一张 Before/After 对照表量化收益：交接从「在 Agent 间粘贴完整输出」变为「按需自动召回」；会话超时不再丢失上下文；跨 N 个 Agent 的上下文从「人工汇总」变为「按项目 tag 检索」；QA 失败恢复从「人工描述错在哪」变为「召回反馈 + rollback 回到已知良好状态」；跨天项目不再需要每会话重建上下文。 适用边界：记忆指令是提示词而非代码，可靠性取决于模型是否按约定打 tag 与召回；且这引入新的数据落盘面——记忆服务器里会留存你的交付物与项目上下文，涉密项目应先确认存储位置与加密策略。

场景四：把「贡献者准入」变成 CI 门禁

业务痛点：282 个 Markdown 由社区贡献，格式稍有偏差（缺 frontmatter、CRLF 行尾、折叠 YAML、代码围栏未闭合）就会在几十个宿主里产生难以察觉的渲染错误。 如何解决：6 个 CI 工作流在合并前强制校验，本地可先跑 lint。

./scripts/lint-agents.sh                      # 扫描全部 18 个部门
./scripts/lint-agents.sh engineering/engineering-frontend-developer.md
./scripts/check-divisions.sh                  # 部门集合三处一致
./scripts/check-tools.sh                      # 工具契约三处一致

收益与量化：lint-agents.sh 对 name/description/color 缺失或为空、CRLF 行尾、折叠 YAML 标量、颜色名不可解析、代码围栏未闭合或非法嵌套直接报 ERROR 并以非零码退出；对缺失推荐章节（Identity/Core Mission/Critical Rules）、正文 < 50 词、soul/agents 两类标题缺失只报 WARN。错误与警告分别计数，结尾给出 Results: N error(s), M warning(s)。 适用边界：它只校验结构，不评判内容——一个形式上完美、实际废话连篇的 Agent 能顺利通过。不建议把它当作质量评审的替代品。

场景五：把事故响应写成可复用 runbook

业务痛点：事故发生时，团队最缺的是分工与交接模板，而这类知识通常散在个人经验里。 如何解决：使用 strategy/ 下的 playbook 与 runbook，把「谁在什么阶段交什么」固化。

# 战略与手册：strategy/nexus-strategy.md · EXECUTIVE-BRIEF.md · QUICKSTART.md
# playbooks：phase-0-discovery.md … phase-6-operate.md
# runbooks：scenario-incident-response.md · scenario-enterprise-feature.md
#           scenario-marketing-campaign.md · scenario-startup-mvp.md
# coordination：agent-activation-prompts.md · handoff-templates.md

收益与量化：check-runbooks.yml 会把 runbook 纳入 CI，保证手册不随仓库演进腐烂；四个 runbook 覆盖从创业 MVP 到企业级特性的典型场景。 适用边界：strategy/ 不是部门（无 agent frontmatter），被明确排除在部门集合之外，因此不会被 --division 选择器安装，需按文档路径直接引用。

六、快速上手

git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents

# 无参数：有 TTY 进交互向导，无 TTY 则自动探测已装工具并全量安装
./scripts/install.sh

# 推荐最小路径：装进 Claude Code（原生格式，无需转换）
./scripts/install.sh --tool claude-code

# 先看清单再动手
./scripts/install.sh --list tools
./scripts/install.sh --list agents
./scripts/install.sh --tool cursor --division engineering --dry-run

在会话里按名字激活即可：Activate Frontend Developer and help me build a React component. 桌面 App 通路为 brew install --cask msitarzewski/agency-agents/agency-agents。环境变量可覆盖路径：CLAUDE_CONFIG_DIR、CODEX_AGENTS_DIR、CURSOR_RULES_DIR、QWEN_AGENTS_DIR、DSH_HOME 等。

七、横向对比

维度	Agency Agents	单宿主角色库	通用 Agent Skill 包	多智能体编排框架
组织单位	角色（282 个 / 18 部门）	角色	任务流程技能	运行时拓扑
跨宿主	17 种（编译式）	1 种	取决于打包	运行时无关
格式正确性保障	CI 门禁（6 个 workflow）	靠人工	多为约定	由框架保证
是否需要运行时	否（纯文件投递）	否	否	需要
跨会话记忆	外挂 MCP（remember/recall/rollback）	一般无	部分有	框架内置
协作编排	声明式（NEXUS + runbook）	无	技能内流程	强（调度/消息）
安装器幂等与不越界	明确保证 + SKIPPED_LOG	手工拷贝	视实现	不适用
内容质量判定	不判定（仅结构）	不判定	不判定	不适用
成本	免费（MIT）+ 宿主模型费	免费	免费	免费或自建
主要风险	内容质量参差、条目过多	供应商锁定	宿主依赖	复杂度与运维

一句话选型：要跨工具复用同一套角色 → Agency Agents；要固化某项目的交付流程 → 与技能包互补使用；要运行时强调度与可观测 → 编排框架；只用一个宿主且角色需求很小 → 直接从本仓库拷几个文件即可，不必引入安装器。

八、局限、风险与社区观察

一、条目数存在明显口径差异，实测为准。 本次 API 实测为 282 个 Agent（divisions.json 所列 18 个部门下的全部 frontmatter 文件）；而第三方站点与社区文章分别称 61（早期）、144+（12 部门）、147+（12 部门）、150+、232（16 部门）。这些数字来自不同时点快照，引用时应注明抓取日期，不要直接采信宣传数字；官方站点 agencyagents.dev 的 146 personas 同属早期口径。

二、「量大」本身就是主要风险。 282 个角色跨 18 个部门，其中 Engineering 65 个、Specialized 59 个，命名与职责必然存在重叠（同时存在 code-reviewer、senior-developer、minimal-change-engineer、codebase-onboarding-engineer）。全量安装带来两个实际后果：选择成本（不知该激活哪个）与宿主容量压力（opencode 约 119 上限）。项目给出的应对是四级筛选，但没有提供质量排序或推荐清单。

三、--path 存在真实的互相覆盖风险，官方已明确警告。 安装器在单目录 --path 场景会校验路径冲突：agent-md 组（claude-code/copilot/gemini-cli/opencode/qwen/zcode）写同类文件名会互相覆盖；agency-skill 组（antigravity/osaurus/dsh）同理。这意味着把多个工具指向同一目录会被静默覆盖，使用 --path 前必须确认目标目录只服务一个工具。

四、质量保证止步于结构。 CI 校验 frontmatter、颜色可解析性、fence 合法性、部门与工具集合一致性，但不评估提示词质量。一个 Agent 的「成功指标」写在文档里作为自我约束，没有自动化去实测。因此实际效果高度依赖所选角色与所用模型，需团队自建评测。

五、维护与治理观察。 正面信号：提交活跃度极高——2026-10-04 单日合并 49 个 PR（#968–#1026），配套 CONTRIBUTING.md（含中文本地化）、SECURITY.md、PR 与 Issue 模板、6 个 CI 工作流；校验脚本注释里留有具体缺陷与修复史（四个 agent 的静默灰、slate/navy 跨四文件漏检），是少见的工程透明度。风险面：GitHub Releases 为 0 条，无版本化发布与变更日志，用户只能跟随 main，回滚路径不清晰；单日 49 个 PR 的节奏也意味着审阅深度需打问号；仓库 topics 与 homepage 均为空，发现性依赖外部传播。

六、许可与合规。 MIT，商业使用友好；但记忆化协作会用到 MCP 记忆服务器，交付物与项目上下文将落到第三方存储，涉密项目需先做数据面评估。

九、小结与行动建议

一句话概括其价值主张：它把「一个角色要想在 N 个智能体宿主里可用」这件事，从复制粘贴的体力活，变成了「一份源 + 一层格式契约 + 一条 CI 门禁」的编译问题。

1. 先只装 1 个工具、1 个部门，跑通再扩。 ./scripts/install.sh --tool claude-code --division engineering，配合 --dry-run 看计划——避开 --path 的多工具覆盖陷阱，也避开 opencode 的 119 上限。
2. 用 --agent 收敛到真正需要的少数角色。 282 个角色的选择成本是真实成本；从 Reality Checker、Code Reviewer、Sprint Prioritizer 这类「有明确把关职责」的角色起步，比全量安装有效得多。
3. 把「成功指标」从文档搬进验收脚本。 Agent 文件里的量化目标只是自我约束，没有任何机制替你实测——这是能立刻补上的最大缺口。
4. 再决定是否引入 MCP 记忆，并同步评估数据面。 记忆能把「你是胶水」变成「Agent 互相召回」，收益明确；但交付物会持久化到记忆服务器，涉密场景先确认存储与加密。
5. 固定一个提交哈希，别裸跟 main。 项目无 Releases、无变更日志，加上单日数十个 PR 的合并节奏，生产使用应锁定 commit，并在升级前跑一遍 lint-agents.sh 与 check-*.sh。

资料来源（抓取日期 2026-10-05）：GitHub REST API（仓库元数据、文件树、提交列表、Releases）；仓库 README.md（84,778 字符）、CONTRIBUTING.md、divisions.json、tools.json、scripts/install.sh、scripts/convert.sh（30,738 字节）、scripts/lint-agents.sh、integrations/claude-code/README.md、integrations/mcp-memory/README.md、examples/workflow-with-memory.md、engineering/engineering-frontend-developer.md；GitHub Trending weekly（2026-10-05）；第三方检索结果（agencyagents.dev、jimmysong.io AI Native Landscape、explainx.ai、Medium/LinkedIn/知乎/腾讯云社区条目与 devtrends）。文中 282 个 Agent 与 18 个部门为本次 API 实测（对全部部门内 282 个 .md 逐一校验 frontmatter name: 字段得到），第三方宣称的 61/144+/147+/150+/232 等数字为不同时点口径，已标注不做采信；GitHub Releases 数为 0，属实测结果。