agency-agents 到底是什么：255 个 agent 的目录，不是一个框架

第一次点开 msitarzewski/agency-agents 这个仓库，很多人的第一反应是「又一个多智能体框架」。截至 2026-08-09 的 GitHub 快照，它有 140729 star、22985 fork、110 个 open issue，主语言标的是 Shell，许可标注为 MIT。一个十几万星的仓库，主语言却是 Shell——这个组合本身就该让人停一下：它不是框架，也没有运行时。

这篇把仓库的结构讲清楚，目的是让你看完能自己回答三个问题：它到底提供什么、它不提供什么、以及你要不要把它放进自己的工作流。

它本质上是一堆 markdown

去掉所有包装，agency-agents 就是一批 markdown 文件：一个 agent 一个 .md，YAML frontmatter 加提示词正文。仓库里另外那组 shell 脚本负责把这批 markdown 转换成各家 AI 编码工具认识的格式，再拷进对应的配置目录。

单个文件是很规整的三层结构，以 engineering/engineering-ai-engineer.md 为例：

---
name: AI Engineer
description: Expert AI/ML engineer specializing in machine learning model development, deployment, and integration into production systems. ...
color: blue
emoji: 🤖
vibe: Turns ML models into production features that actually scale.
---

# AI Engineer Agent

You are an **AI Engineer**, an expert AI/ML engineer specializing in ...

## 🧠 Your Identity & Memory
- **Role**: AI/ML engineer and intelligent systems architect
...

YAML frontmatter → 角色声明段 → 分节的职责与规则正文。正文是直接喂给模型的第二人称提示词。scripts/lint-agents.sh 第 34 行把必填字段写死为三项：

REQUIRED_FRONTMATTER=("name" "description" "color")

emoji 和 vibe 出现在样例里，但不在必填列表，属可选字段；vibe 是一句话人设标语，被目录类工具消费。

这里要先立一条读法上的规矩。frontmatter 与正文里那些第二人称句子——比如 Experience: You've built and deployed ML systems at scale——是写给模型的人设设定，不是对任何真人履历的陈述。把它当成「这个 agent 背后有大规模 ML 经验」来理解，是从第一步就读错了。

本节延伸

• 一个 agent 文件长什么样：frontmatter、角色声明、分节正文
• agency-agents 的 agent 文件格式：name/description/color 是必填，emoji/vibe 不是

255 而不是 316：数错了会推出错误结论

带 frontmatter 的 agent markdown 一共 255 个，分布在 17 个 division：

目录	展示名	agent 数
engineering	Engineering	58
specialized	Specialized	57
marketing	Marketing	36
gis	GIS	13
security	Security	12
design	Design	10
sales	Sales	9
testing	Testing	9
paid-media	Paid Media	7
project-management	Project Management	7
academic	Academic	6
game-development	Game Development	6
spatial-computing	Spatial Computing	6
support	Support	6
finance	Finance	5
product	Product	5
healthcare	Healthcare	3

按 git 树统计，仓库里的 markdown 文件总数约 316，比 255 多出六十来个。差额不是「还有六十个 agent 没被收录」，而是 README、CONTRIBUTING、strategy/ 下的编排文档、examples/ 这类非 agent 文件。把 316 说成 316 个 agent，是这个仓库最常见的一处误传。

为什么必须数准？因为这个数字直接决定安装成本。装 255 个 agent 到某些工具就是落 255 份产物，这跟落 316 份、或者跟你以为的「几十个」，是完全不同量级的决定。

什么目录不是 division

divisions.json 的 _note 字段专门写了一句：并非每个顶层目录都是 division。scripts/check-divisions.sh 里用 NON_DIVISION_DIRS 排除了四个：

• integrations/——scripts/convert.sh 写出的每工具转换产物，是输出不是输入
• strategy/——playbook 与 runbook，没有 agent frontmatter，是编排方法论而不是可安装的 agent
• examples/、scripts/——同样排除

判断规则很干脆：一个目录要成为 division，必须至少包含一个带 frontmatter 的 agent 文件。

这条规则的实际价值在于，当你想「我只要工程类的」而去 cp 某个目录时，得先确认那个目录里装的是源 agent 还是产物。往 integrations/ 里找源文件，或者指望 strategy/ 下的文档能被安装，都会白忙。

本节延伸

• 17 个 division 与那四个「不是 division」的目录
• check-divisions.sh 失败：四个地方要同步改
• 一份 JSON 管住五个脚本：单一真相源是怎么落地的

没有运行时，只有两步流水线

框架会有调度、有状态、有 agent 之间的消息传递。agency-agents 这些都没有。

这里要防一处误会：strategy/ 下确实有一套叫 NEXUS 的编排文档，QUICKSTART.md 把这个缩写展开为 Network of EXperts, Unified in Strategy，还分了 Phase 0 到 Phase 6 七个阶段、给了 NEXUS-Full / NEXUS-Sprint / NEXUS-Micro 三种激活模式和交接文档模板。但它全部写在 markdown 里，靠提示词让模型自己按阶段推进，没有任何代码在强制执行阶段顺序或质量门。把它当成「编排引擎」或「自动化框架」来预期，装完只会失望。divisions.json 的 _note 也直说了 strategy/ 放的是编排方法论、不是可安装的 agent。

回到真正的链路，只有两步：

源 agent markdown → convert.sh 渲染成各工具格式 → integrations/ → install.sh 拷贝到目标目录。

install.sh 从 integrations/ 读已转换的文件往各工具配置目录拷；集成文件缺失或过期时它会自己先调 convert.sh，这个自动行为可以用 --no-convert 关掉。到此为止——之后 agent 怎么被调度、怎么被激活，是 Claude Code、Cursor 这些消费方自己的事，跟这个仓库无关。

tools.json 收录了 16 种工具。理解产物形态的关键是 installKind 这个字段，tools.json 的 _note 把它定义为安装机制，并说明它是「上游真相，对每个消费方都成立」。三种取值：

• per-agent——每个 agent 渲染出一个文件或一个目录。绝大多数工具属于这一类。
• roster——所有 agent 合并成一个文件。Aider 的 CONVENTIONS.md、Windsurf 的 .windsurfrules 是这一类。
• plugin——一个构建出来的产物，不能按 agent 渲染成字符串，在所有消费方都只能走 CLI。Hermes 是唯一一个。

这三个词就是判断依据。 如果你在找「为什么 Aider 里没法只装某一个 agent」，答案不在文档的某个角落，就在 installKind: roster——它的产物形态压根不是一 agent 一文件。而 Hermes 的 plugin 意味着连官方 app 都装不了，只能命令行。

format 字段是另一层契约：同一个 format 名保证渲染出字节级相同的输出。所以 claude-code 与 copilot 共用 identity（顾名思义就是原样输出、不做改写），osaurus 与 antigravity 共用 skill-md。_note 最后一句也要如实带出：渲染器覆盖面是消费方自己的事，由 format 推导，目录本身不携带任何 app 发布状态。

本节延伸

• per-agent、roster、plugin：三种安装机制决定了你能不能只装一个
• 同名 format 保证字节级相同输出：一条被写进注释的契约
• NEXUS 是什么：写在 markdown 里的多 agent 编排方法论

两个反直觉的设计

第一个在 lint 里。lint-agents.sh 的 classify_header_target() 会把每个 ## 级标题分流：命中 identity、learning + memory、communication、style、critical rule、rules you must follow 的进 SOUL.md，其余全进 AGENTS.md。这两个文件名对应的是 convert.sh 里 OpenClaw 格式的工作区结构。也就是说，你给章节起的标题看起来只是排版，实际上是路由。lint 要求两边都至少有一个标题，否则各报一条 WARN。

第二个在 Cursor 的转换产物里。cursor-mdc 渲染出的 .mdc frontmatter 是这样：

---
description: ${description}
globs: ""
alwaysApply: false
---
${body}

alwaysApply: false 和 globs: "" 是写死的。转换出来的 Cursor 规则默认不会自动生效，需要在 Cursor 里按需引用。如果你装完 Cursor 侧发现「像没装一样」，先回这一行看。

本节延伸

• 给 agent 章节起标题其实是在写路由：agency-agents 的 SOUL.md / AGENTS.md 分流机制
• Cursor 里装完没反应？看一眼 alwaysApply: false

仓库自己给的质量边界

这一段值得单独说，因为它决定了你对这 255 个文件该抱什么预期。

lint-agents.sh 的五道检查是：拒绝 CRLF 行尾（ERROR）、frontmatter 分隔符存在（ERROR）、必填字段齐全（ERROR）、推荐章节存在（WARN）、正文词数少于 50 就警告（WARN），外加上面那条标题映射的 WARN。注意 ERROR 和 WARN 的分界——推荐章节 Identity / Core Mission / Critical Rules 缺了只是警告，不会让检查失败。

更要紧的是：lint 检查的是结构，不评估提示词好不好用。 一个 frontmatter 齐全、章节完整、正文超过 50 词的文件，可以照样是一段没什么用的提示词。

check-agent-originality.sh 补的是另一个洞：换皮抄袭。脚本自述的动机是，把已有 agent 做一次查找替换（比如换掉国家名或平台名）在评审里很难发现，格式规范也能合并，但会用重复内容把库撑肿。算法是把候选 agent 与整个花名册对比，用实体中性化后的 8 词 shingle 重叠率打分，让换掉的专有名词藏不住。默认阈值 ORIGINALITY_FAIL 为 40、ORIGINALITY_WARN 为 20（均可用环境变量覆盖）；源码注释给出的库内校准数据是：现有库里同一对之间最差相似度约 1.5%、中位数 0%。所以双位数就是强异常，默认阈值留了很宽的误判安全边界。

这两个数据是库内校准值，不是对任意 agent 库的普适结论。但它给了你一个有用的参照：如果你自己维护一批提示词，两两相似度普遍在个位数以下，才算是真的各写各的。

本节延伸

• lint 报了一屏：哪些必须修，哪些可以先放着
• agency-agents 排查：body seems very short，50 词这条线是怎么来的
• 换个国家名就想混过去？8 词 shingle 重叠率不答应

那么，你该怎么用

README 的 Quick Start 给了三条路。第一条是装官方桌面 app（README 标为 Recommended，仓库 msitarzewski/agency-agents-app，站点 agencyagents.app，macOS 可用 brew install --cask msitarzewski/agency-agents/agency-agents）——我们没有下载或运行过这个 app，只能转述 README 的说法。第二条是配合 Claude Code 用脚本：

./scripts/install.sh --tool claude-code
# 或只要某一个 division
cp engineering/*.md ~/.claude/agents/

第三条最容易被忽略：不装，当参考资料读。255 个文件本身就是一份提示词写法的样本集，尤其是它们怎么组织 Identity / Core Mission / Critical Rules 这几段。

如果你决定装，有两个开关值得先用上。--dry-run 只打印安装计划、不写任何东西，在往 ~/.claude/agents/ 这类共享目录落两百多个文件之前先看一眼，成本极低。--division 与 --agent 用来收窄范围——一次性把 255 个 agent 灌进全局配置目录是有代价的（上下文占用、工具启动时的加载、命名冲突），具体影响多大我们没有测过，不给数字，但收窄这件事本身几乎不需要犹豫。

平台方面，脚本注释写明支持 Linux、macOS（需要 bash 3.2 以上）以及 Windows 的 Git Bash / WSL。Windows 用户注意这是 shell 脚本，PowerShell 或 cmd 里直接跑不了，得在 Git Bash 或 WSL 环境里执行。

最后一句关于那 140729 个 star：它说明关注度高，仅此而已。它不告诉你这些提示词适不适合你的项目、你的模型、你的语言。这个判断只能你自己做，而做判断的材料，就是上面那几条——它是目录不是框架、255 而不是 316、产物形态由 installKind 决定、lint 只管结构不管质量。

本节延伸

• 把 agency-agents 装进 Claude Code：从 convert 到 install 的完整链路
• 往 ~/.claude/agents/ 写 200 多个文件之前，先跑 --dry-run
• 按你的角色选 division：agency-agents 不用一次全装

专题全部内容

本专题共 40 篇，按下面五组读。每组内部大致由浅入深，不必按顺序通读——按你当下卡在哪一步挑着看即可。

机制与文件格式

先搞清楚它是怎么组织的，后面装到哪、为什么这样转换才有依据。

• 一个 agent 文件长什么样：frontmatter、角色声明、分节正文
• agency-agents 的 agent 文件格式：name/description/color 是必填，emoji/vibe 不是
• 给 agent 章节起标题其实是在写路由：agency-agents 的 SOUL.md / AGENTS.md 分流机制
• 17 个 division 与那四个「不是 division」的目录
• per-agent、roster、plugin：三种安装机制决定了你能不能只装一个
• 同名 format 保证字节级相同输出：一条被写进注释的契约
• 为什么 runbook 引用 slug 而不是显示名
• 一份 JSON 管住五个脚本：单一真相源是怎么落地的
• 换个国家名就想混过去？8 词 shingle 重叠率不答应

安装与格式转换

16 种工具、16 个落点。装之前先看这一组，尤其 —dry-run 那篇。

• 把 agency-agents 装进 Claude Code：从 convert 到 install 的完整链路
• 16 种工具、16 个落点：一张表搞清装到哪去了
• 往 ~/.claude/agents/ 写 200 多个文件之前，先跑 --dry-run
• agency-agents 安装选择器实战：—tool/—division/—agent/—agents-file 怎么组合
• Codex 的 TOML 转换：为什么正文要走 basic string
• --link 符号链接模式：改动自动传播的好处与代价
• 12 个环境变量：不想装进默认目录时改哪里
• --parallel 与 --jobs：多工具安装的并行控制
• Windows 上怎么装：Git Bash、WSL 与 bash 3.2 的门槛

排查

装完没反应、lint 报一屏、CI 校验失败——按症状找。

• Cursor 里装完没反应？看一眼 alwaysApply: false
• 明明开头就是三个横杠，为什么报 missing frontmatter
• lint 报了一屏：哪些必须修，哪些可以先放着
• agency-agents 排查：body seems very short，50 词这条线是怎么来的
• integrations/ 缺失或过期时到底发生了什么
• check-divisions.sh 失败：四个地方要同步改
• check-tools.sh 失败：加一个工具要动三处
• runbook 里的 slug 解析不到 agent 文件时怎么查
• 255 个 agent 全装进全局目录，代价是什么

NEXUS 多 Agent 编排

它是一套写在 markdown 里的方法论，不是调度器——这一组讲清楚它能与不能。

• NEXUS 是什么：写在 markdown 里的多 agent 编排方法论
• Full、Sprint、Micro：三种模式各自适合什么活
• Phase 0 到 Phase 6：七个阶段的分工与产出
• 那段激活提示词逐句拆解：它到底在要求模型做什么
• Startup MVP runbook：9 个常驻 agent 加两组按需
• 事故响应 runbook：为什么「修完」之后还有一组人
• 每个阶段之间都有质量门，所有评估都要有证据
• 交接文档、QA 失败反馈、升级报告：三个模板的用法

选型与自建

该不该用、用哪几个、还是照它的规范自己写。

• 这套东西该不该用：先问自己四个问题
• 按你的角色选 division：agency-agents 不用一次全装
• 用现成的 agent 还是自己写：一个务实的判断路径
• 照它的规范写自己的 agent：五道检查逐条对齐

---

本文依据 agency-agents 官方仓库（github.com/msitarzewski/agency-agents）的 README、 tools.json、divisions.json、scripts/ 下的安装与校验脚本整理，核对日 2026-08-09。 本文内容为仓库源码与文档口径，我们没有安装或运行过其中任何 agent。 目录、脚本与安装路径随上游更新而变动，请以仓库最新内容与 ./scripts/install.sh --help 的实际输出为准。

许可条款请以官方 LICENSE 原文为准，本文不构成法律意见。