把 293 个 AI 专家装进你的编程工具:Agency Agents 全解析

想让 AI 以「资深前端工程师」的身份帮你 review 代码，你通常得先写一段几百字的人格 prompt：它是什么角色、说话什么风格、关注哪些点、输出什么格式。写完这个角色，想把它换到 Cursor 或 Codex 上再用，往往又要为另一个工具的格式重写一遍。

一个角色可以手写，一支团队就写不动了。当你要的不只是「一个工程师」，而是架构师、安全专家、营销策划、测试工程师凑成的一队人时，手写和重复适配的成本会指数级上升。

msitarzewski/agency-agents（The Agency）就是冲着这个矛盾来的：把 293 个专业 AI 人格定义做成一套可安装、可门禁、可多工具分发的库，让你在任何主流的 AI 编程工具里一键召唤一支「AI 专家队」。

msitarzewski/agency-agents — 把 293 个专业 AI Agent 人格定义装进你的编程工具：17 个职能分部、16 种工具一键安装、质量门禁驱动社区协作（MIT · 141.9K+ star · 2026-08 实测）。

它的设计核心可以概括成一句话：一个 agent 文件，处处运行。所有 agent 用同一套数据模型编写，一个脚本把它编译成十几种工具各自认得的格式，另一个脚本把它装进你机器上已装的工具。这也是它跟「prompt 收集仓库」最本质的区别：它有编译期，也有门禁。

这篇按「它到底是什么 → 快速上手 → 避坑 → 核心架构 → Claude Code 实战 → 工程与社区 → 安全 → 适用边界」的路径讲透，其中核心架构和 Claude Code 实战是重点。

一、它到底是什么：人格库，不是技能，也不是编排引擎

要理解 Agency Agents，先要拆掉两个常见的误会。

它不是 Skill（技能包）。 Skill 给 AI 增加的是「会做什么」：一组操作流程、方法、工具使用手册。而这里每个 agent 文件写的是「你是谁」：身份、沟通风格、必须遵守的规则、成功指标。装不装它，AI 都会写代码；装了它，AI 会以「资深前端工程师」的身份和标准来写。打个比方，Skill 是给员工的培训手册，Agency Agents 是给员工的名片和工牌。

它也不是多 Agent 编排引擎。 仓库里没有调度器、没有 agent 之间的消息协议、没有任务分配机制。它提供的是一批互相独立的角色素材，至于怎么让这些角色配合，是宿主工具和用户的事。真正会自己编排多个 agent 协作的，是 Pi、Swarm、Autogen 这类框架，Agency Agents 可以当它们的角色配置来源。

那它落到 Claude Code 里是什么？是 subagent。每个 agent 文件放进 .claude/agents/ 目录后，主 Claude 会把它当做一个可委派的独立助手，通过 Agent 工具启动它干活。这部分细节放在第五章展开。

一句话定位：一套「人格模板 + 角色库 + 分发管线」，既给单 agent 换身份，也给多 agent 组队供素材。

二、快速上手

2.1 三条安装路径

路径 A：桌面 App（新手推荐）。官方维护了一个原生桌面应用 Agency Agents，支持 macOS / Linux / Windows，图形界面里浏览全部 roster、勾选要装哪些、一键装进 Claude Code、Cursor、Codex 等，还能自动更新。不想碰终端的人走这条路最省事。

路径 B：命令行脚本（可精确控制）。克隆仓库后用脚本安装：

路径 C：手动复制。最轻量，想用哪个就复制哪个：

2.2 在 Claude Code 里激活

装完后，在 Claude Code 会话里直接引用 agent 名：

主 Claude 会匹配到对应的 subagent，加载它的完整人格（身份、核心使命、工作流、成功指标）后执行任务。如果装了多个职能分部，会话里会出现一组可选的专业角色，按需召唤即可。

三、避坑指南（实测经验）

以下是实际使用中最容易遇到的情况，先摆出来免得走弯路。

3.1 frontmatter 的 name 与官方 subagent 规范不完全一致

Claude Code 官方规定 subagent 的 name 字段用小写连字符（如 code-reviewer），而 Agency Agents 里的 agent 文件，name 写的是大写加空格（如 Code Reviewer），另外带 color、emoji、vibe 这类 Claude Code 不认识的自定义字段，其中 color 大量使用 hex 色值，而官方只认 8 个命名色。

实际影响：文件放在 .claude/agents/ 后能被识别为 subagent（最低要求只有 name + description），但 @ 引用时到底用哪个名字，取决于当前 Claude Code 版本的容错。如果发现匹配不上，把 frontmatter 的 name 改成小写连字符即可，这是一个 30 秒的文本替换。

3.2 安装后的文件名带职能分部前缀

用脚本安装时，文件是原样复制的，所以 engineering/engineering-code-reviewer.md 装完还是叫 engineering-code-reviewer.md，而不是 code-reviewer.md。引用 agent 时要用带前缀的名字，这点容易一开始摸不着头脑。

3.3 Windows 用户必须在 Git Bash / WSL 里跑脚本

脚本是 bash 写的，原生 cmd / PowerShell 跑不了。另外仓库强制 LF 行尾，如果用 Windows 编辑器改坏过 frontmatter 导致报错，把文件转回 LF 即可。

3.4 OpenCode 有容量上限

如果你用 OpenCode，注意它上游有个限制，只能注册约 119 个 agent，超出部分会静默丢弃。安装器会主动警告，按职能分部收敛到限制以内即可。

四、核心架构：一个带「编译期」的专家库

这一节是全文重点。Agency Agents 之所以能从 2025 年 10 月的 51 个 agent 长到现在的近 300 个还不失控，靠的不是内容多，而是它把「内容工程」做出了编译期和门禁。

图：Agency Agents 的完整管线——单一数据源 → 质量门禁 → 多格式编译 → 多工具安装 → 运行时

4.1 单一数据源：一个 agent 就是一个文件

每个 agent 是一个 markdown 文件，头部是 YAML frontmatter，正文是九个固定小节。这套结构是机器强制的数据契约，不只是写作规范：

frontmatter 里的 name 字段是全项目的唯一标识，脚本从它派生 slug（Code Reviewer → code-reviewer），保证转换、安装、过滤永远指向同一个 agent。正文的九个小节按语义分成「人格组」（身份、沟通风格、必须遵守的规则）和「操作组」（核心使命、交付物、工作流、成功指标），这个分组不是给人看的规范，是给脚本看的分类依据。

4.2 编译期：一个文件渲染成 14 种格式

这是整个架构的枢纽。convert.sh 读全部 agent 文件，为 14 种目标工具渲染对应格式，写入集成目录：

关键的设计取舍：转换产物不提交进仓库，由用户在本地生成，.gitignore 排除。这样避免了「293 个文件 × 14 种格式」约 4000 份产物入库带来的版本膨胀和合并冲突。

同一份人格定义要喂给 TOML、YAML、SKILL.md 这些格式，中间有不少真实的工程处理：比如 Codex 要的 TOML 里，agent 正文含引号、换行、emoji，必须做控制字符转义才能生成合法文件；OpenCode 要求的颜色是 hex，脚本要把命名色映射成色值，认不出来的兜底成灰色。

4.3 安装期：一个纯 bash 写出来的交互向导

install.sh 是另一个重头，它有 1300 多行，内含一个不依赖任何第三方库的交互式安装向导。运行后会在终端渲染出三屏选择界面：第一屏选工具（自动检测你机器上装了什么）、第二屏选职能分部、第三屏确认安装。支持键盘导航、搜索过滤、实时汇总，全程只用了 bash 自带的能力。

这个交互界面是纯手工实现的：处理终端的 raw 模式、逐字节解析方向键的转义序列、无闪烁地整帧重绘。它把「给不懂命令行的用户提供良好安装体验」这件事，做到了零依赖。

4.4 质量门禁：让社区贡献不失控

一个近 300 个 agent、全部来自社区 PR 的项目，质量控制是生死线。Agency Agents 用三层门禁把「这个新 agent 合不合格」变成机器可判定：

结构门禁。一个 lint 脚本检查 frontmatter 必填字段、行尾格式、正文小节是否齐全、内容是否够长。缺字段直接报错，PR 无法合并。

相似度门禁。这是最有意思的一个：一个脚本用「8 词滑动窗口 + Jaccard 相似度」比较新 agent 和全库已有 agent 的文本重合度，而且会先把国家名、平台名这类专有名词从文本里抹掉再比较。这样做的目的是拦住「换皮」贡献：有人把已有的「越南市场」agent 里几个地名换成「中国市场」就当新 agent 提交，抹掉专有名词后文本重合度立刻暴露，机器直接判重复。阈值是重合度达到 40% 判失败，而全库正常 agent 之间的最高重合度只有 1.5%，留足了安全余量。

一致性门禁。项目的职能分部和工具列表各有一份 JSON 作为唯一事实源，配套脚本交叉校验 JSON、磁盘目录、脚本里的数组、CI 的路径过滤是否一致。哪一处漂移了，构建就失败。这个设计源于一次真实事故：曾经有职能分部因为某处硬编码列表忘了同步，导致新加的分部在安装器和 CI 里都静默消失。

三层门禁全部挂在 CI 上，每次 PR 自动跑。这也是「gated」一词在这个项目里的含义：agent 是过了门禁才合并进来的。

五、在 Claude Code 里组队用

5.1 @ 调用 = subagent 委派，不是角色扮演

这是最值得弄清的一点。在 Claude Code 里用 @名字 引用一个 agent，底层的机制是 subagent 委派，而不是让主 Claude「扮演」那个角色：

主 Claude 收到消息后，找到对应的 subagent 文件，通过 Agent 工具启动一个独立的实例去干活。这个实例有自己独立的上下文窗口，它看不到你主对话的历史，只有自己的系统提示（agent 文件内容）加上委派任务。干完活，只有最终总结回到主对话。

跟「扮演」的本质区别在于上下文是否隔离：

判断有没有真的走 subagent 委派，看对话里是否出现一行 Agent 工具调用（形如 engineering-code-reviewer (Code Reviewer)），以及 subagent 的中间过程是否不可见。如果想让 agent 用到主对话的上下文，就不该用委派，而是直接让主 Claude 以该角色处理。

5.2 实战模板：让几个专家并行研究一个本地项目

这套 agent 最典型的用法是「组队」。比如想快速搞懂一个本地克隆下来的开源项目，可以并行派三个角色，各管一摊：

三个 subagent 各自独立上下文并行干活，互不干扰，结果回到主对话后再由第四个角色汇总。这就是「hub-and-spoke」的团队形态：主 Claude 是调度者，agent 是隔离的执行者。它们不能互相直接通信，需要主 Claude 中转，但用来并行研究、审查、写作已经足够。

5.3 官方推荐用法速查

六、工程素养与社区

Agency Agents 是一个社区驱动项目的样本。它从 Reddit 上一个关于「AI 专业分工」的帖子起步，12 小时内收到 50 多个需求，演化到今天 141.9K stars、23.1K forks、90+ 贡献者。不到一年，从 51 个 agent 长到近 300 个。

工程上值得一提的几点：

• 零依赖。核心脚本全部用系统自带的 bash、awk、grep、sed 写成，兼容 macOS 自带的 bash 3.2，不要求用户装 Node、Python 或任何运行时（Hermes 插件除外）。
• 单一事实源贯穿。职能分部、工具列表、runbook 各有一份 JSON 当权威，脚本全部从它派生，杜绝硬编码漂移。
• 多语言生态。社区维护了 8 个翻译项目（中、日、韩、葡、俄、印尼、阿拉伯、越南），中文翻译项目里还有针对中国市场的原创 agent。

七、安全性评估

对一个「要装进你的开发工具、要运行脚本」的开源项目，安全性值得单独看。实测结论很干净：

• 零第三方依赖。没有 package.json、没有 pip 依赖，供应链投毒无从谈起。
• 零网络请求。脚本全部本地运行，不向任何服务器上报数据，没有遥测、没有崩溃上报、没有版本检查回传。
• 零敏感信息读取。不碰你的 SSH 密钥、云凭证、环境变量。
• 有安全策略文档。官方维护 SECURITY.md，定义了漏洞上报流程，并明确要求贡献者不得在 agent 文件里嵌入可执行代码或密钥。

唯一需要留意的不是代码层面，而是内容层面：agent 是社区贡献的提示词，理论上存在 prompt injection 的风险。官方文档自己也在安全策略里提醒「不要向 agent 透露敏感信息」。对敏感场景，先审阅你要用的那个 agent 内容再激活，是合理的习惯。

八、适用场景与总结

适合

• 个人开发者效率提升：把常用的几个专业角色（前端、架构、安全审查）装进 Claude Code，随叫随到。
• 团队统一 AI 资产：按职能分部只装团队需要的角色，全队用同一套专业人格。
• 学习 prompt 工程：近 300 个 200 到 400 行的高质量人格定义，是最好的案例库，每个都带工作流、成功指标、代码示例。
• 多工具用户：一份人格库，convert 一次，Claude Code、Cursor、Codex 全都能用。

谨慎

• OpenCode 用户：受 119 个 agent 容量上限限制，需要按分部收敛。
• 对 agent 输出完全信任：它是社区内容，关键场景结合自己的判断。

不适合

• 想独立运行 agent：这只是人格定义，必须有 Claude Code、Cursor 这类宿主工具才能跑。
• 对内容来源极度敏感：所有 agent 来自社区 PR，虽然有三层门禁，但理论上存在注入风险。

回到开头那个矛盾：一个角色可以手写，一支团队就写不动了。Agency Agents 给出的答案是先把「角色」这个元素工程化——统一的文件格式、可编译的多格式分发、可机器判定的质量门禁——再让社区往里灌内容。它没有发明新的 agent 运行时，但它把「如何规模化地生产和分发 AI 角色」这件事，做成了目前开源社区里最完整的样本之一。下一支 AI 团队，可能真的不需要你亲手招人，只需要一条 install 命令。