用现成的 agent 还是自己写：一个务实的判断路径

2026-08-09

「现成的 agent 好用吗」这个问题没法直接回答，因为它把两件不同的事混在了一起：一件是你要的能力，另一件是你要的写法。agency-agents 这个仓库把两者同时摆在货架上——它本质上是一批带 YAML frontmatter 的 markdown 文件，你既可以让脚本把它们拷进工具的配置目录直接用，也可以只把它们当提示词范本读。选错了方向，装完一堆文件却发现自己真正缺的是第二种，那就白折腾了。

下面这条判断路径，是按「你的处境」而不是「产品的特性」排的。每一步都给一个可执行的判断动作，走到哪一步得出结论就在哪一步停。

第零步：先确认你要的是能力还是写法

仓库 README 的 Quick Start 给了三条路，注意第三条：

装官方桌面 app（README 自己标为 Recommended）；
配合 Claude Code 用脚本安装：./scripts/install.sh --tool claude-code，或者只要某一个 division，cp engineering/*.md ~/.claude/agents/；
当参考资料用——不安装，直接读提示词的写法。

第三条常被跳过，但它往往才是收益最高的一条。如果你的真实困境是「我不知道一个专业角色的提示词该分几段、每段写什么」，那你需要的是范本，不是安装。把仓库 clone 下来读几个文件，成本几乎为零，也不用担心配置目录被塞满。

顺便说一句环境：上面两条命令都是 shell 命令，Windows 上别在 cmd 或 PowerShell 里直接敲，要在 Git Bash 或 WSL 这类能跑 shell 的环境里执行。仓库在 GitHub 上的主语言标注就是 Shell。

判断动作：问自己一句「我是想让模型现在就换个角色干活，还是想学会怎么写这种角色文件」。答案是后者，到这一步就可以停了。

第一步：去花名册里找对口的，而不是凭印象猜

截至 2026-08-09 核对，仓库里带 frontmatter 的 agent markdown 共 255 个，分布在 17 个 division。这里有个很容易踩的坑：仓库里 markdown 文件总数大约 316 个，但那个数字里包含 README、CONTRIBUTING、strategy/ 下的编排文档、examples/ 等非 agent 文件。255 才是 agent 数，316 不是。

分布很不均匀，这直接影响你「能不能找到对口的」：

division	agent 数
`engineering`	58
`specialized`	57
`marketing`	36
`gis`	13
`security`	12
`healthcare`	3

工程和「专项」两块加起来就占了一百多个，落在这两块的需求，找到同名角色的概率明显高于落在 healthcare（3 个）这种薄区的需求。

还有一点值得知道：不是每个顶层目录都是 division。divisions.json 的 _note 字段明确写了，integrations/ 是 scripts/convert.sh 写出的每工具转换产物、strategy/ 放的是没有 agent frontmatter 的 playbook 与 runbook，加上 examples/、scripts/，这四个目录在 scripts/check-divisions.sh 里通过 NON_DIVISION_DIRS 被排除。你在 strategy/ 里翻到一份写得很好的文档，它不是一个可安装的 agent。

判断动作：打开花名册去检索关键词，别凭印象编 agent 名字。engineering 目录下有 engineering-rag-pipeline-engineer、engineering-i18n-engineer、engineering-privacy-engineer、engineering-wechat-mini-program-developer 这类相当细分的条目，也确实没有你脑补出来的那个名字。找不到就是找不到，往下走。

第二步：名字对口 ≠ 内容对口

找到同名角色只是第一层筛选。第二层要看正文，因为这批文件的厚度差异极大。同样在 engineering 目录下，engineering-code-reviewer 正文约 418 词，engineering-git-workflow-master 约 385 词，而 engineering-multi-agent-systems-architect 约 4354 词。四百词的文件和四千词的文件，能给模型的约束密度完全不是一回事——前者更像一句加长的角色声明，后者才写进了具体流程。

文件结构固定为三层：YAML frontmatter → 角色声明段 → 分节的职责与规则正文。正文是直接喂给模型的第二人称提示词，形如 You are an **AI Engineer**, ...。

这里有条必须提醒的红线：frontmatter 与正文里出现的 Experience: You've built and deployed ML systems at scale 这类句子，是写给模型的人设设定，不是对任何真人履历的陈述。它不构成能力背书，你不能因为读到这一句就认为这个 agent 在你的场景下靠谱。

判断动作：把候选文件真的打开读一遍正文，看它写的流程是不是你要的那个流程。如果读完发现「方向对，但一半章节和我的场景无关」，那结论多半是第五步的混合路线，而不是直接装上。

第三步：三个信号说明只能自己写

以下三种情况，花名册里再多角色也帮不上：

信号一，你的约束是私有的。 内部框架、私有 API、公司发布流程、只有你们团队才有的评审规则——公开仓库里的 agent 不可能知道这些。这类知识必须自己写进正文，没有捷径。

信号二，你要的是一次性任务。 为一件只做一次的事去挑选、转换、安装一个 agent，走完流程的成本高于直接把要求写在对话里。agent 文件的价值在于复用，不复用就不划算。

信号三，你需要对输出格式做强约束。 现成 agent 的正文是按通用场景写的，你要求的产出格式（固定字段、固定分节、固定校验项）它不会正好命中。改到命中所需的编辑量，常常已经接近重写。

第四步：自己写一份，成本到底有多少

好消息是格式门槛很低。scripts/lint-agents.sh 第 34 行的必填字段只有三个：

---
name: <角色名>
description: <这个角色做什么>
color: <颜色>
---

缺任意一项 lint 报 ERROR。样例文件里还出现了 emoji 和 vibe，这两个不在必填列表里，属于可选字段——vibe 是一句话人设标语，会被 app 一类的目录工具消费。

坏消息是有个看起来只是排版、实际上是路由的隐藏规则。lint-agents.sh 里的 classify_header_target() 会把每个 ## 级标题分流到两个目标：标题里命中 identity、learning + memory、communication、style、critical rule、rules you must follow 的，归到 SOUL.md；其余全部归到 AGENTS.md。lint 要求两边都至少有一个标题，否则各报一条 WARN。也就是说，你给章节起的标题会直接决定这段内容被转换到哪个产物文件里。第一次写的人几乎不可能猜到这一点，写完发现整份文件都落进同一个产物，就是标题起得太自由。

lint 的检查分两级，从第 0 道编号到第 5 道：0（拒绝 CRLF 行尾）、1（frontmatter 分隔符存在）、2（必填字段齐全）是 ERROR；3（推荐章节 Identity / Core Mission / Critical Rules 存在）、4（正文词数少于 50 就警告）、5（标题能映射到两个目标文件）是 WARN。WARN 不会让检查失败，别把两者混为一谈。

第 0 道检查值得单独说：源码注释解释了为什么要专门拒绝 CRLF——行尾多一个 \r 会让后面的 frontmatter 检查报出令人困惑的「missing frontmatter ---」，而你明明看到文件开头就写着 ---。Windows 上用编辑器新建文件写 agent 的人，这一条是最可能第一次就撞上的。

另外还有一道 scripts/check-agent-originality.sh。它的动机很直白：把已有 agent 做一次「查找替换换皮」（比如把国家名或平台名一换），在评审里很难发现——能合并、格式也规范——但会用重复内容把库撑肿。算法是把候选 agent 与整个已有花名册对比，用实体中性化后的 8 词 shingle 重叠率打分，被中性化的专有名词包括 vietnam/vietnamese/china/chinese/douyin/tiktok/korea/korean/japan/japanese 等，所以换掉的专有名词藏不住。默认阈值 ORIGINALITY_FAIL 为 40、ORIGINALITY_WARN 为 20（两个都可以用环境变量覆盖）；源码注释给出的库内校准数据是：现有 agent 库里同一对之间最差的相似度约 1.5%，中位数 0%，所以双位数就属于强异常。

这套质量门是这个仓库自己的标准，要不要套到你的私有 agent 库上由你决定。但它检查的是结构与重复度，不评估提示词好不好用——lint 全绿不代表这个 agent 有效。

第五步：多数人的答案其实是混合路线

走到这里，最常见的落点不是二选一，而是：拿现成 agent 当骨架，自己补差量。现成文件替你解决的是分节结构、角色声明的写法、职责与规则怎么排；你补的是私有约束、输出格式、团队流程。第三步那三个信号里，通常只有一两个成立，而不是全部成立。

不过要注意上面那道原创性检查透露出来的态度：仓库明确把「换皮」视为要拦住的东西。你自建私有库当然不受它约束，但换个角度，如果你的「自己写」只是把某个现成 agent 的名词换了一遍，那你其实没有得到新东西。这条提醒对私有库同样成立。

我们不比的几个维度

哪个 agent 效果更好、提效多少：我们一个 agent 都没安装过、没运行过，官方也没给这类数据，不比。
和其它 agent 集合的横向对比：本文事实来源只覆盖这一个仓库，不比。
star 数说明什么：2026-08-09 的快照是 140729 star、22985 fork、110 个 open issue。这只说明关注度，不能由此推导质量、稳定性或它是否适配你的项目。
许可能怎么用：仓库标注为 MIT，具体商用边界、二次分发条件请以官方 LICENSE 原文为准，本文不做解读。

一页速查

你的处境	结论
想学角色提示词怎么写	当参考资料读，别装
需求落在 engineering / specialized 这类厚区，且读完正文确认流程对口	直接用现成的
名字对口但正文只有几百词、约束太稀	当骨架，自己补
约束是私有的（内部框架 / 私有 API / 团队流程）	自己写
一次性任务	不做 agent，直接在对话里说清要求
对输出格式有强约束	自己写，或大幅改写现成的

最后强调一遍第一步的那个判断动作：要引用具体 agent，回花名册核对 slug，不许凭印象编名字。 这个仓库有 255 个 agent，凭感觉写出来的名字有很大概率不存在，而不存在的 slug 会让你后面每一步都在排查一个假问题。

延伸阅读

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