这套东西该不该用：先问自己四个问题

2026-08-09

有人在群里丢过来一个链接问「这个要不要用」，我第一反应从来不是去看它有多少 star。star 数只说明有多少人点过收藏，说明不了它跟你手头这套工具链合不合得上。

agency-agents（github.com/msitarzewski/agency-agents）就是这样一个容易被 star 数带偏的项目。截至 2026-08-09 的 GitHub 快照，它有 140729 star、22985 fork、110 个 open issue，主语言标的是 Shell，许可标注为 MIT。这些数字唯一能推出的结论是「关注度高」，推不出它稳定、好用或者适合你——所以下面这篇不比效果，只比条件。

先把它是什么说清楚

选型最容易翻车的地方，是没搞明白买的到底是什么。

agency-agents 的本体是一批 markdown 文件：每个 agent 一个 .md，YAML frontmatter 加提示词正文，正文是第二人称写给模型的（“You are an …”）。按仓库脚本对各 division 目录的统计，带 frontmatter 的 agent markdown 共 255 个，分布在 17 个 division，最大的三个是 engineering（58）、specialized（57）、marketing（36）。

这里有个数字陷阱值得先钉住：仓库里 markdown 文件总数按 git 树统计约 316，比 255 多出来的那批是 README、CONTRIBUTING、strategy/ 下的编排文档、examples/ 之类的非 agent 文件。看到把 316 直接当成 agent 数量的说法，那是把仓库文件总数当成花名册了。

除了 markdown，仓库还提供两个东西：scripts/convert.sh 负责把源 agent 渲染成各家工具认识的格式，scripts/install.sh 负责把 integrations/ 里的转换产物拷到对应配置目录。integrations/ 是产物目录不是源目录——这一点在 divisions.json 的 _note 里写明了。

所以你要评估的不是「一个 AI 产品」，而是「一份提示词语料 + 一套 Shell 安装管道」。想清楚这一点，后面四个问题才问得下去。

问题一：你的工具在这 16 种里吗，是哪一种安装机制

tools.json 里列了 16 种工具。但比「在不在名单里」更要紧的是 installKind 字段，它定义了安装机制，只有三个取值：

installKind	含义	谁属于这一类
`per-agent`	每个 agent 渲染出一个文件或一个目录	名单里的绝大多数，如 Claude Code、Codex、Gemini CLI、Cursor
`roster`	所有 agent 合并成一个文件	Aider（`CONVENTIONS.md`）、Windsurf（`.windsurfrules`）
`plugin`	构建出来的产物，不能按 agent 渲染成字符串	Hermes，唯一一个

这一栏直接决定了你能不能「只要几个」。如果你的主力是 Aider 或 Windsurf，产物形态本身就不是一 agent 一文件，「只装一个 Frontend Developer」这个诉求在机制上就不成立。如果你用 Hermes，tools.json 的口径是它只能走命令行安装。

tools.json 的 _note 还定义了 format 的契约：同一个 format 名保证渲染出字节级相同的输出。这就是 claude-code 与 copilot 都用 identity、osaurus 与 antigravity 都用 skill-md 的原因（identity 顾名思义是原样输出，不做格式改写）。_note 最后一句也要如实带出：渲染器覆盖面是消费方自己的事，目录本身不携带任何 app 发布状态。

还有一条对 Cursor 用户特别重要。convert.sh 渲染的 .mdc 文件，frontmatter 里 globs: "" 和 alwaysApply: false 是写死的：

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

意思是转换出来的规则默认不自动生效，得在 Cursor 里按需引用。如果你的预期是「装完就有」，这一条会直接改变你的判断——不是坏了，是设计如此。

问题二：你要的是提示词素材，还是一套流程

README 的 Quick Start 给了三种用法：装官方 app（标为 Recommended）、配合 Claude Code 跑脚本、以及当参考资料读，根本不装。第三种经常被跳过，但它对很多团队是最划算的一种。

如果你的真实需求是「我想知道一个领域专家提示词该怎么分节、该写哪些约束」，那 255 个 markdown 摊在那里就是现成的语料，不装也能看。lint 脚本推荐的三个章节 Identity、Core Mission、Critical Rules 就是一份现成的骨架。

如果你的需求是「多个 agent 怎么配合」，仓库里还有 strategy/ 目录，里面是叫 NEXUS 的一套编排文档（N-E-X-U-S = Network of EXperts, Unified in Strategy）。它定义了三种激活模式和七个阶段（Phase 0 Discovery 到 Phase 6 Operate），文档给出的建议尺度是 NEXUS-Full 用全部 agent、12–24 周，NEXUS-Sprint 用 15–25 个、2–6 周，NEXUS-Micro 用 5–10 个、1–5 天。这些是文档建议的时间尺度，不是承诺，也不是测出来的。

★ 这里有一条必须说清的边界：NEXUS 是写在 markdown 里的方法论，不是可执行的调度器。 它靠提示词让模型自己按阶段推进，没有任何代码在强制执行阶段顺序或质量门。divisions.json 的 _note 也明确写了 strategy/ 里没有可安装的 agent。你要是奔着「一个能自动派活的编排引擎」来的，方向就错了。

反过来，如果你要的是方法论文本本身，它的密度是够的：七个 playbook 各自成文，nexus-strategy.md 里还有 Handoff Document、QA Failure Feedback、Escalation Report 三个交接模板。runbooks.json 提供了四个可直接照搬的场景（startup-mvp、enterprise-feature、marketing-campaign、incident-response），并且引用 agent 时一律用 slug 而不是显示名——_note 给的理由是显示名带前缀、会漂移，slug 抗改名、可测试。这条经验跟这个仓库本身没关系，你自己项目里做跨文件引用也该这么干。

问题三：装到哪一层，家目录还是这个项目

这是我认为最该在动手前想明白的一问，因为它决定的是影响半径。

install.sh 的注释里列出的落点，家目录与当前目录是混着的：claude-code 是 ~/.claude/agents/，codex 是 ~/.codex/agents/，osaurus 是 ~/.osaurus/skills/；而 opencode、cursor、aider、windsurf 这四个写的是当前目录（分别是 .opencode/agents/、.cursor/rules/、CONVENTIONS.md、.windsurfrules）。

也就是说，同一条命令在不同工具上，一个是给整个账户装，另一个是给你当下 cd 进去的那个项目装。在错误的目录里回车，后果不一样。

顺带提醒一处不能类推的地方：tools.json 里 opencode 的用户级模板是 .config/opencode/agents/{slug}.md，跟 install.sh 注释写的「当前目录 .opencode/agents/」不是同一个位置——这两处分别对应不同 scope。要断言某个具体路径，回源文件核对当前 scope，别混着说。

如果目标目录不合心意，install.sh 的注释列了一组环境变量，它们在硬编码默认值之前被检查，包括 CLAUDE_CONFIG_DIR、CURSOR_RULES_DIR、CODEX_AGENTS_DIR、OPENCODE_AGENTS_DIR、GEMINI_AGENTS_DIR 等。另外还有 --path <dir> 可以覆盖安装目录（单一目标），--link 可以用符号链接代替拷贝，好处是上游改动会自动传播。

把 255 个 agent 一次性铺进全局配置目录是有代价的——上下文占用、工具启动时的加载、命名冲突都在其中。具体影响多大我们没有测过，不给数字；但用 --division 或 --agent 收窄，是成本更低的起步方式。

问题四：它的质量门到底管什么

仓库确实带了质量门，但要看清楚门管的是哪一层。

lint-agents.sh 有五道检查：拒绝 CRLF 行尾（ERROR）、frontmatter 分隔符存在（ERROR）、必填字段 name / description / color 齐全（ERROR）、推荐章节存在（WARN）、正文词数少于 50 报警告（WARN），外加一条章节标题能否映射到两个目标文件的 WARN。注意 WARN 不会让检查失败。

check-agent-originality.sh 做的是重复检测：把候选 agent 与整个花名册做实体中性化后的 8 词 shingle 重叠比对，默认 ORIGINALITY_FAIL=40、ORIGINALITY_WARN=20（两者都可用环境变量覆盖）。源码注释给出的库内校准结论是：现有 agent 之间最差的相似度约 1.5%，中位数 0%——所以双位数就算强异常，默认阈值留了很宽的安全边界。

看到这里结论应该很清楚了：这套检查管的是结构与重复度，不评估提示词好不好用。 它拦得住换皮抄袭和缺字段，拦不住一段写得很漂亮但对你业务没用的提示词。

同一个道理还适用于 agent 正文里那些句子。frontmatter 与正文里写的 “You’ve built and deployed ML systems at scale” 这类表述，是写给模型的人设设定，不是任何真人的履历，更不是能力背书。把它当成质量证明，是这类提示词库最常见的误读。

把四问串成一条路径

按顺序走，任何一步答「不行」都可以直接停。

顺序	问题	答什么算过	答不上来时去哪查
1	我的工具在 16 种里吗	在，且 `installKind` 允许我按需选	`tools.json`
2	我要素材还是要流程	要素材 → 可以不装；要流程 → 明白 NEXUS 是文档不是引擎	README 的 Quick Start、`strategy/`
3	装家目录还是项目目录	明确知道这条命令写到哪	`install.sh` 注释与 `tools.json` 的 `dest`
4	我接受质量门只管结构吗	接受，并打算自己评估提示词	`lint-agents.sh`、`check-agent-originality.sh`

四问都过了再动手，第一条命令建议是先看不写：

./scripts/install.sh --list tools
./scripts/install.sh --tool claude-code --division engineering --dry-run

--dry-run 只打印计划、不写任何东西，是这个仓库对新手最有价值的一个开关——往共享配置目录写文件之前，先把计划看一眼。选择器（--tool / --division / --agent / --agents-file）可以自由组合，全空就是全装。以上为按官方参数语义组合的示例，未逐项实测，以官方文档与 ./scripts/install.sh --help 的实际输出为准。

Windows 这边多一步：脚本注释写的平台支持是 Linux、macOS（需要 bash 3.2+）、Windows 的 Git Bash / WSL。也就是说 PowerShell 或 cmd 里直接敲这条命令不是它设计的用法，先把 Git Bash 或 WSL 准备好再说。

哪些维度我们不比

选型文章最容易掺水的地方是硬凑对比维度，这里明说三条不比的：

不比效果。 我们没有安装过其中任何一个 agent，也没有运行过 install.sh 或 convert.sh，任何「用了以后提效多少」的说法都没有依据。
不比与其它提示词库的优劣。 手头只有这一个仓库的事实，跨项目横评需要另一边同等颗粒度的材料。
不解读许可边界。 仓库标注为 MIT，仅此而已；商用范围、二次分发条件一律以官方 LICENSE 原文为准。

最后回到开头那个问题。要不要用，取决于你答完这四问后手里剩下什么：如果剩的是「工具对得上、我只装两三个 division、装在项目目录、提示词质量我自己把关」，那它就是一份成本很低的起步语料；如果剩的是「我指望它自动帮我编排一整个团队」，那这个仓库交付不了这件事——不是它不行，是它本来就不是干这个的。

延伸阅读

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