把 agency-agents 装进 Claude Code：从 convert 到 install 的完整链路

2026-08-09

很多人第一次接触 agency-agents，会以为它是个需要”安装”的软件。其实不是。按仓库 README 的自述，它就是一批打磨过的 AI agent 人格集合，落到磁盘上是一个 agent 一个 .md 文件：YAML frontmatter 加提示词正文。截至 2026-08-09 的核对，带 frontmatter 的 agent markdown 共 255 个，分布在 17 个 division 目录里。

既然是 markdown，那”装进 Claude Code”到底装的是什么？答案是拷贝——把这些 markdown 按目标工具认识的格式渲染一遍，再放到该工具会去读的配置目录。整条链路只有两段脚本，搞清楚这两段，后面所有开关都好理解。

一、链路只有两段：convert 在前，install 在后

scripts/install.sh 的头部注释把它自己的职责写得很明确：从 integrations/ 读取已转换的文件，拷到每个工具对应的配置目录；如果 integrations/ 缺失或过期，先跑 scripts/convert.sh。

所以顺序是：

源 agent markdown（各 division 目录）
  → scripts/convert.sh 渲染成各工具格式
  → integrations/（产物目录）
  → scripts/install.sh 拷贝到目标配置目录

integrations/ 是产物，不是源。divisions.json 的 _note 里明确把它和 strategy/、examples/、scripts/ 一起排除在 division 之外。改 agent 内容要改 division 目录下的源文件，改 integrations/ 会被下一次 convert 覆盖。

默认情况下 install.sh 在集成文件缺失时会自动调 convert，所以多数时候你只需要跑一条命令。想显式关掉这个自动行为，用 --no-convert。

二、Claude Code 这一路的落点和格式

tools.json 里对 16 种工具各定义了一行契约。Claude Code 这一行只需要记三个字段：

字段	值	意味着什么
`format`	`identity`	原样输出，不做格式改写
`installKind`	`per-agent`	每个 agent 渲染出一个文件
`dest.user`	`.claude/agents/{slug}.md`	用户级落点

identity 是这 16 种工具里最省心的一档——tools.json 的 _note 说明了 format 的契约含义：同一个 format 名保证渲染出字节级相同的输出，所以 claude-code 和 copilot 能共用 identity。换句话说，Claude Code 拿到的文件和仓库里的源 markdown 在格式上没有改写层，看不懂产出物的时候直接去看源文件就行。

per-agent 决定了另一件事：你选几个 agent，就落几个文件。选了整个 engineering，就是 58 个文件。这一点和 Aider、Windsurf 的 roster（所有 agent 合并成一个 CONVENTIONS.md / .windsurfrules）完全不同，别拿别处的经验往这边套。

用户级还是项目级，是这篇里最容易踩的坑。Claude Code 的 dest.user 与 dest.project 模板都是 .claude/agents/{slug}.md，区别只在于这个相对路径落在家目录还是当前项目目录。install.sh 的注释里给 claude-code 标的是 ~/.claude/agents/。要断言某个具体 scope 的落点，回 tools.json 现查，不要靠猜。

三、命令怎么写

README 的 Quick Start 给的最短形式就一行：

./scripts/install.sh --tool claude-code

这一行的语义是：只装 Claude Code 这一个工具，agent 范围不限——按 USAGE 段的说法，选择器全空就等于全装。要补一句的是，USAGE 里同时写了交互向导在终端里默认是开的（--interactive / --no-interactive 控制），所以你在 TTY 里敲这一行，未必是直接哗啦啦落盘。真要执行之前，还是先把下面这几个开关过一遍。

先看再写。install.sh 提供了 --list，接 tools、teams 或 agents，列出后直接退出；以及 --dry-run，只打印计划、不写任何东西。

# 只看有哪些 agent，不做任何事
./scripts/install.sh --list agents

# 打印安装计划，不落盘
./scripts/install.sh --tool claude-code --division engineering --dry-run

--dry-run 是这个仓库对新手最有价值的一个开关。往 ~/.claude/agents/ 这种全账户共享的目录一次性写进去两百多个文件，出事之后清理起来比看一眼计划麻烦得多。

把范围收窄。四个选择器可以自由组合，全空等于全装：

参数	含义
`--tool <a,b>`	只装这些工具
`--division <a,b>`	只装这些 division
`--agent <slug,slug>`	只装指定 agent
`--agents-file <path>`	从文件读 agent 列表

--agents-file 是团队协作里最实用的一个：每行一个 slug 或名字，支持 # 注释。把它提交进项目仓库，新人拉下来跑同一条命令就得到同一套 agent，比在群里贴一长串逗号分隔的 slug 靠谱：

# team-agents.txt
engineering-backend-architect
engineering-code-reviewer
design-ux-architect

./scripts/install.sh --tool claude-code --agents-file ./team-agents.txt --dry-run

要不要用符号链接。--link 用符号链接代替拷贝，改动会自动传播。如果你打算跟着上游更新，或者自己会去改 division 目录下的源文件，链接省掉每次重装的一步；如果你要的是一份不受 git pull 影响的稳定快照，就老实拷贝。

换个落点。两条路：--path <dir> 覆盖安装目录（单一目标）；或者用环境变量，install.sh 的注释列出的可覆盖变量会在硬编码默认值之前被检查，Claude Code 对应的是 CLAUDE_CONFIG_DIR。

CLAUDE_CONFIG_DIR=<你的目标目录> ./scripts/install.sh --tool claude-code --agent engineering-code-reviewer --dry-run

并行开关先放着。--parallel 是并行安装各工具、输出按工具缓冲，--jobs N 控制最大并行数（默认取 nproc 或 4）。注意它并行的粒度是”工具”，你只装 Claude Code 一个工具时，这两个开关没有用武之地。

以上为按官方参数语义组合的示例，未逐项实测，以官方文档与 ./scripts/install.sh --help 的实际输出为准。

四、Windows 上怎么跑

脚本注释里写的平台支持是：Linux、macOS（需要 bash 3.2 以上）、Windows Git Bash / WSL。

这是 .sh 脚本，PowerShell 和 cmd 直接跑不了。Windows 用户实际只有两个选择：Git Bash，或者 WSL。两者的差别不在能不能跑，而在家目录是谁的家——WSL 里的 ~ 是 Linux 侧的家目录，跟 Windows 侧那个装着 Claude Code 配置的家目录不是同一个位置。如果你在 WSL 里跑完发现 Windows 侧的 Claude Code 没变化，先去确认这一条，再考虑用 --path 或 CLAUDE_CONFIG_DIR 显式指到你要的位置。

另外，lint-agents.sh 的第一道检查就是拒绝 CRLF 行尾，仓库标准是 LF（.gitattributes 里有规定）。源码注释解释了原因：行尾多一个 \r 会让后面的 frontmatter 检查报出令人困惑的”missing frontmatter ---“，明明文件开头就是 ---。Windows 上克隆仓库如果被 Git 自动转换了行尾，这个坑迟早会碰上。

五、产出物长什么样，怎么验收

因为 Claude Code 走的是 per-agent + identity，产出物形态是可以从契约推出来的：目标目录下一个 agent 一个 .md 文件，文件名是 agent 的 slug，内容与源 markdown 在格式上没有改写层。人工验收看三处：

文件数量和你的选择器对不对得上。 选了 --division engineering 就该是 58 个文件；数量对不上，多半是选择器写错了 division 名，或者 integrations/ 是旧的。
文件名是不是你要的那些 slug。 slug 带 division 前缀，engineering-code-reviewer 这样。写错 slug 是 --agent 和 --agents-file 最常见的失败方式。
--dry-run 打出的计划和实际落盘的目录一致。 这是最省事的一次对照，尤其在你同时用了 --path 或环境变量的时候。

至于”装完之后 Claude Code 里会怎么显示”——我们没有安装、也没有运行过其中任何一个 agent，这篇不做任何描述。README 里给的激活示例原文是 "Hey Claude, activate Frontend Developer mode and help me build a React component"，具体行为以你自己的环境为准。

六、什么情况别这么干

别一上来全量装。 255 个 agent 一次性写进全局配置目录是有代价的：上下文占用、工具启动时的加载、命名冲突，都是真实存在的成本。这里不给任何量化数字，因为我们没测过。但用 --division 或 --agent 从一个 division 起步，成本明显更可控。

别拿别的工具的结论套过来。 16 种工具里 installKind 分三类：per-agent、roster、plugin。Aider 和 Windsurf 是 roster，产物形态就不是一 agent 一文件，“只装某一个 agent”在那边不成立；Hermes 是唯一的 plugin，tools.json 说明它是构建出来的产物、不能按 agent 渲染成字符串，在所有消费方都只能走 CLI。还有一个反直觉的：Cursor 的转换产物 frontmatter 里 alwaysApply: false 和 globs: "" 是写死的，也就是转出来的规则默认不会自动生效——如果你在 Cursor 那边装完觉得”没反应”，多半就是这一条，而不是 Claude Code 这边的问题。

别在错误的目录里执行。 install.sh 注释里，claude-code、codex、gemini-cli、copilot 这些落的是家目录，而 opencode、cursor、aider、windsurf 四个写的是当前目录。混装多工具时，你 cd 在哪里直接决定了后四个装到谁头上。

自己写 agent 要过仓库自己的门。 仓库带了原创性检查脚本，把候选 agent 与整个花名册做实体中性化后的 shingle 重叠率比对，默认 ORIGINALITY_FAIL 是 40、ORIGINALITY_WARN 是 20（都可用环境变量覆盖）。源码注释给的库内校准值是：现有 agent 之间最差相似度约 1.5%、中位数 0%。也就是说双位数就已经是强异常了。但要说清楚，lint 和原创性检查管的是结构与重复度，不评估提示词好不好用。

最后提一句关注度：这个仓库在 2026-08-09 的快照里 star 数是 140729。这个数字只说明关注度，不说明它适配你的项目，也不说明装进来的 agent 一定比你自己写的提示词好用。真正决定体验的是你选了哪几个 agent、装在哪个 scope，以及有没有在落盘前先 --dry-run 看一眼。

延伸阅读

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