照它的规范写自己的 agent：五道检查逐条对齐

2026-08-09

想给 agency-agents 加一个自己的 agent，最常见的做法是找一个顺眼的现成文件复制一份，把名字和领域一换就交上去。这条路走到评审那一步经常会卡住，而且卡住的原因往往不是”写得不好”，是仓库里有一整套脚本在管结构。

这篇不打算把字段表整个搬一遍。要写一个能过仓库那几道门的 agent，你在动手之前得先做五个选择，每个选择都有明确的判断依据。我们按顺序过一遍，从你的处境倒推到结论。

需要先说清楚的前提：以下全部来自对仓库源码与文档的阅读。我们没有安装过其中任何一个 agent，没有运行过 lint-agents.sh 或 check-agent-originality.sh，所以下文不会出现任何”跑起来是什么样”的描述。

选择一：这个 agent 到底该不该新写

先别写文件，先回答一个问题：你想加的这个角色，和花名册里已有的 255 个（分布在 17 个 division）是不是同一件事换了个说法。

仓库对这件事的态度写在 scripts/check-agent-originality.sh 的脚本自述里，大意是：新 agent 应该是真的新东西；把已有 agent 做一次查找替换换皮——比如把国家名或平台名一换——在评审里很难被发现，它能合并、格式也规范，但会用重复内容把库撑肿。

它的算法是把候选 agent 与整个已有花名册做对比，用实体中性化后的 8 词 shingle 重叠率打分。所谓实体中性化，就是先把一批专有名词抹平再比对，源码里被中性化的词包括 vietnam/vietnamese、china/chinese、douyin/tiktok、korea/korean、japan/japanese 等（源码注释说明这个列表会随新市场出现继续扩充）。换句话说，靠替换专有名词来”改写”是藏不住的。

两个默认阈值可以用环境变量覆盖：

变量	默认值	含义
`ORIGINALITY_FAIL`	`40`	达到或超过该百分比视为重复，退出码 1
`ORIGINALITY_WARN`	`20`	达到或超过该百分比出警告，不失败

为什么阈值定这么高？源码注释给出了库内校准结论：在现有 agent 库里，同一对之间最差的相似度约 1.5%，中位数 0%。所以双位数就已经是强异常，默认值留了很宽的误判余量。注意这两个数是这个库自己的校准值，不是对任意 agent 库的普适结论。

决策路径：如果你打算做的只是”把某个已有 agent 换个行业/换个地区”，重叠率大概率不会低——与其去和阈值较劲，不如去改那个已有 agent，或者把你的差异点重新想清楚，让它在职责、流程、产出物上真的不一样。反过来，如果你写的是库里没有的领域，这一关基本不需要惦记。

用法上它有两种模式：给文件参数就只查这几个（CI 用来查变更文件），不给参数就全库两两互查（审计模式）。它依赖 python3，环境里没有会直接退出码 2。脚本注释里对平台的说法是 Linux、macOS（bash 3.2+）、Windows Git Bash / WSL；至于你机器上 python3 这个命令名到底存不存在，那是本地环境问题，不在仓库文档的口径里，跑之前自己先确认一下。

选择二：放进哪个 division，要不要新建一个

现有 17 个 division 里能塞下就别新建。新建 division 不是建个目录那么简单，scripts/check-divisions.sh 会强制要求 division 列表与磁盘目录、convert.sh 和 lint-agents.sh 里的 AGENT_DIRS 数组、以及 lint-agents.yml 的路径过滤器四处一致，不一致就让构建失败。

如果确实需要新建，divisions.json 的 _note 给了正确顺序：建目录 → 在 divisions.json 加条目 → 跑 scripts/check-divisions.sh → 按它的报错去更新它指向的地方。顺序反了你就是在几个文件之间来回猜。

顺带一个容易误判的点：并不是每个顶层目录都是 division。integrations/ 是 convert.sh 写出的转换产物，strategy/ 放的是 playbook 与 runbook、没有 agent frontmatter，examples/ 和 scripts/ 同理，这四个在 check-divisions.sh 里通过 NON_DIVISION_DIRS 排除。一个目录要成为 division，必须至少包含一个带 frontmatter 的 agent 文件——所以”先建空目录占位”这种做法在这里是走不通的。

选择三：frontmatter 填几个字段

lint-agents.sh 第 34 行写死了必填列表：

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

name、description、color 三项，缺任意一项报 ERROR。样例文件 engineering/engineering-ai-engineer.md 里还出现了 emoji 和 vibe，这两个不在必填列表里，属可选字段。

那要不要写？判断依据是下游谁消费它。vibe 是一句话人设标语，会被 app 一类的目录工具拿去展示；color 除了 lint 必填，在转换到 opencode 格式时还会经 resolve_opencode_color() 解析成十六进制。所以：只求过 lint，三项就够；希望它在目录类界面里有一行像样的自我介绍，就补上 vibe。

还有一条写作层面的提醒。样例 agent 的正文里有 Experience: You've built and deployed ML systems at scale 这样的句子——这是写给模型的人设设定，不是任何真人的履历。你自己写的时候可以照这个体例，但别把它当成能力证明拿去对外宣传。

选择四：章节标题怎么起——这是路由，不是排版

这是整套规范里最反直觉的一条，也是这篇最想让你记住的一条。

lint-agents.sh 的 classify_header_target()（第 40–53 行）会把每个 ## 级标题按关键词分流到两个目标文件：

标题里命中的关键词	落到哪
identity、learning + memory、communication、style、critical rule、rules you must follow	SOUL.md
其余全部（mission、deliverables、workflow 等）	AGENTS.md

匹配是大小写不敏感的。lint 要求两边都至少有一个标题，否则各报一条 WARN：no section headers map to SOUL.md in convert.sh / ... to AGENTS.md in convert.sh。

这两个文件名不是凭空来的，它对应的是 convert.sh 里 OpenClaw 的 openclaw-workspace 格式——那种格式下一个 agent 渲染成一个目录，正文按同一套关键词拆成 SOUL.md 与 AGENTS.md（外加 IDENTITY.md），默认桶是 agents。也就是说，你随手给章节起的标题，实际上决定了这段内容将来被转换到哪个产物文件里。

决策路径：如果你的目标工具里包含 OpenClaw，这条是硬约束，得刻意安排——人格、沟通风格、铁律放进能命中 SOUL 关键词的标题，任务、交付物、工作流留给 AGENTS。如果你只装 Claude Code（identity 格式原样输出）或 Cursor（cursor-mdc 把正文整段塞进 ${body}），拆分对产物没有影响，但 lint 那两条 WARN 还是会照报——而 WARN 不会让检查失败，你可以自己权衡要不要迁就它。

选择五：正文写多长，行尾用什么

长度上 lint 只有一条底线：正文词数 少于 50 就报 WARN（同样只是警告）。它不管你写得好不好用——这一点必须说清楚，lint-agents.sh 校验的是结构，不评估提示词质量。

想找参照量级可以看花名册的导出：academic-statistician 正文约 1669 词，design-persona-walkthrough 约 2438 词，academic-narratologist 约 884 词。这是库内既有样本的分布，不是任何官方推荐值。

行尾这一条对 Windows 用户是刚需：lint 的第 0 道检查直接拒绝 CRLF，级别是 ERROR。 仓库标准是 LF（见 .gitattributes）。源码注释还解释了为什么要单独拦这一条——行尾多一个 \r 会让后面的 frontmatter 检查报出令人困惑的 missing frontmatter ---，可你打开文件一看，开头明明就是 ---。在 Git Bash 或编辑器默认 CRLF 的环境里写 agent，这大概是最容易浪费半小时的一个坑。

五道检查一览与等级

把上面几节对应回 lint-agents.sh 的检查序列，等级分清楚很重要：

#	检查	级别
0	拒绝 CRLF 行尾	ERROR
1	frontmatter 分隔符存在	ERROR
2	必填字段齐全（`name`/`description`/`color`）	ERROR
3	推荐章节存在（Identity / Core Mission / Critical Rules）	WARN
4	正文词数 ≥ 50	WARN
5	章节标题能映射到 SOUL.md 与 AGENTS.md 两边	WARN

三条 ERROR 是硬门，三条 WARN 是建议。用法是 ./scripts/lint-agents.sh [file ...]，不给文件则扫描所有 agent 目录。

哪些维度我们不比

提示词写得好不好用：仓库里没有任何一个脚本在做这件事，我们也没有运行过任何 agent，这个维度没有依据，不比。
加进来之后效果如何：同上，一次都没跑过，不做任何效果、耗时、提效方面的描述。
和其它 agent 集合的横向优劣：这个仓库在 2026-08-09 的快照里 star 数为 140729，关注度不低，但关注度不能推导出质量、稳定性或是否适配你的项目，这一条不构成选型依据。
许可与商用边界：仓库标注为 MIT，具体条款以官方 LICENSE 原文为准，本文不解读。

什么情况可以不管这套规范

如果你写的 agent 只是自己在本地用、根本不打算提交回上游，那五道检查里对你真正有意义的其实只有 frontmatter 那两条 ERROR——因为你的目标工具要读它。章节标题的分流规则只在你会用 convert.sh 转成 OpenClaw 工作区时才起作用；原创性检查是仓库为了控制库体积做的门，跟你自己的一个文件没关系。

另一种情况：你不是要新增，而是要改一个已有 agent。那么原创性检查这一关的语义就反过来了——你改的幅度越小，与原文的重叠度越高，越不应该以”新 agent”的身份提交，而是直接改那个文件。

延伸阅读

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