用 agents-md-writer 优化你的 AGENTS.md

最近我写了一个 agent skill：agents-md-writer。

它做的事情很简单：让 agent 写 AGENTS.md 的时候，先去仓库里探测，只写验证过的东西，写完自己跑一遍检查。

GitHub：https://github.com/RUIIIOVO/agents-md-writer

为什么写这个

起因是我发现，让 AI「给这个项目写一份 AGENTS.md」，产出基本都很差。差得还挺有规律：

写没跑过的命令。仓库里 package.json 根本没有 test script，它照样写「运行 npm test」。
写不存在的路径。它抄 README，不看文件系统，README 一旧它就跟着错。
写死开发机路径，/Users/alice/dev/project 直接进文件，换台机器就废了。
写三百行「编写清晰、可维护的高质量代码」这种话。

前三条是错误，能一眼看出来。第四条最麻烦，因为它看起来「没毛病」。

AGENTS.md 是每次会话开始时被完整注入 上下文的。你往里塞的指令越多，所有指令的遵循率一起往下掉，不只是新加的那条。所以一份塞满套话的 AGENTS.md，不光浪费 token，还会把你真正在意的那几条规则稀释掉。

左边这份，每次会话都要花预算注入一遍，但里面没有一句是可执行的。「Code is well written」这种验收项，agent 想怎么解释都行，等于没写。

第二个原因更私人一点：我自己攒了几条给 agent 的规矩，想把它们固定下来，不用每个项目重新交代一遍。比如这两条，是我现在全局配置里最有用的：

markdown 复制代码

- 本轮改动了文件就在回复末尾列出全部改动文件的**完整路径**，标注新增/修改/删除，
  不要只说「已更新」。
- 需要我拍板的事项一律收在回复最末尾的「待你确认」块，编号列出。
  每条写成：一句话说清问题 → 列 A/B/C 选项及各自代价 → 标出你推荐哪个并说明理由。

第一条治「它到底改了什么我得自己翻」，第二条治「它自作主张选了一条路还不告诉我有别的选项」。

但这两条属于个人偏好 ，换个仓库依然成立，所以它们该待在全局配置里，不该复制进每个项目的 AGENTS.md。这个区分我也写进了 skill：它会主动把这类规则往全局挪，把「本仓库的提交格式是 feat(scope):」这类事实留在项目里。

支持哪些 agent

skill 本身遵循 Agent Skills 规范，任何加载 skill 的工具都能用。安装脚本目前覆盖：Claude Code、Codex、pi、omp、Hermes、ZCode、WorkBuddy。

它写出来的 AGENTS.md，这些工具会直接读：Codex、pi、omp、OpenCode、Grok CLI、Kimi Code、OpenClaw、DeepSeek Harness、Hermes、GitHub Copilot。Claude Code 和 Gemini CLI 需要一个入口文件指过去。逐个 agent 的路径矩阵和证据在仓库的 references/agent-registry.md 里。

Gemini CLI 没有 skill 机制，装的时候会退化成往 ~/.gemini/GEMINI.md 追加一个带标记的引用块。它只是叫模型去读那个文件，没有 progressive disclosure，可靠性比真 skill 差一截。

安装

最省事的办法：把这句话直接贴给你正在用的 agent。

text 复制代码

安装这个 skill：https://github.com/RUIIIOVO/agents-md-writer

自己动手就两条命令：

bash 复制代码

git clone https://github.com/RUIIIOVO/agents-md-writer.git ~/.agents/skills/agents-md-writer
~/.agents/skills/agents-md-writer/scripts/install.sh

第一条把 skill 放到 ~/.agents/skills/ 这个共享位置，第二条只链到你当前用的那个 agent，其他的不碰。

安装脚本怎么知道装到哪：你在终端里手动跑，它列出本机的 agent 让你选；由 agent、管道或 CI 调用，它自己认出调用者，不弹提示。重复跑不会出错。

几个常用参数：

bash 复制代码

./scripts/install.sh --all          # 本机所有 agent 都链上
./scripts/install.sh --agent codex  # 指定一个
./scripts/install.sh --dry-run      # 只看计划，不改东西
./scripts/install.sh --where        # 输出 agent 和路径两行就退出

实体只有一份，各 agent 各链一条软链过去。git pull 一次，所有链上的 agent 都是新的，不会分裂成好几份副本。

Windows 用 scripts/install.ps1，建的是目录联接（junction），不需要管理员权限，也不用开发者模式。

装完问一句「你现在有哪些 skill」就能确认。

三种用法

装完之后不用再跑任何命令，也不用记 slash command。走哪一条，看你怎么说。

一、给项目写一份

在项目目录里打开 agent，直接说：

text 复制代码

给这个项目写一份 AGENTS.md

这一条就一句话：先探测，绝不猜。

skill 会要求 agent 先跑一遍 ls -A、读 package.json / pyproject.toml / Cargo.toml、find 找 Makefile、git log --format=%s -20 看提交风格，然后才动笔。README 里写了但仓库里不存在的命令，直接不写进去，或者标成「已知缺口」。

写完它会自己跑一遍 lint，再按 12 项自检清单过一遍。如果你用的是 Claude Code，它还会建一个只有一行 @AGENTS.md 的 CLAUDE.md 当入口，而不是复制两份内容出来各自跑偏。

二、检查现有的

text 复制代码

检查一下我的 AGENTS.md

这一条只读不改 。它给你一句结论（能用 / 要修 / 建议重写），加一张 位置 → 问题 → 建议 的清单。你没点名要改哪个，它一个字都不动。

也可以直接盘点整台机器：

text 复制代码

检查一下我电脑上所有的 AGENTS.md

这里有个细节我写进 skill 了：定位文件必须走 Spotlight 索引（macOS 的 mdfind、Linux 的 plocate），禁止在 home 目录上做无限制递归扫描 。不写死这条，agent 很容易一个 find ~ -name AGENTS.md 下去，然后卡在那里。实在没有索引，也要求限定目录和 -maxdepth。

三、整理已经写臃肿的

text 复制代码

这个 CLAUDE.md 四百行了，整理一下

这一条会先 cp CLAUDE.md CLAUDE.md.bak 备份并告诉你备份在哪，然后把每一段分类，先给你一张表：

去处	什么内容
留在项目	项目事实：目录结构、命令、边界、约定
上提到全局	个人偏好：语言、输出风格、本机环境
下沉到子目录	只跟某一个模块相关的规则
移到 skill	多步骤流程、低频的专门知识
删除	过期内容、元规则、手填日期、一次性需求

你过目确认之后它才动手。这一步我特意做成两段式的，因为「整理」这个动作删起来没有边界，让 AI 自己决定删什么太危险。

lint 脚本

12 项自检里有 5 项是纯机械的，所以单独做成了脚本，不依赖 AI 判断：

检查项	级别
存在 YAML frontmatter	error
写死开发机路径（`/Users/x/`、`/home/x/`、`C:\`）	error
手填日期（`YYYY-MM-DD`）	warning
反引号里的路径在磁盘上不存在	warning
行数超过 200	warning

bash 复制代码

./scripts/lint-agents-md.sh                     # 默认检查 ./AGENTS.md
./scripts/lint-agents-md.sh AGENTS.md docs/sub/AGENTS.md
pwsh -File scripts/lint-agents-md.ps1 AGENTS.md # Windows

退出码 0 表示没有 error，1 表示至少有一个，可以直接挂到 CI 上。NO_COLOR=1 关彩色输出。

脚本只依赖 bash 3.2+（macOS 自带的那个版本）、zsh 或 PowerShell 5.1+，没有外部依赖，不用装 node 也不用装 python。

两个注意点：

lint 按被检查文件所在目录解析路径，所以要在真实仓库里跑。
别拿它检查 SKILL.md，skill 文件本来就该有 frontmatter。

写出来的东西长什么样

摘一段仓库里的样例（examples/after.md）：

markdown 复制代码

## Environment & commands

Prerequisites: Node 20+, pnpm 9+, Docker (for Postgres).

- **Install**: `pnpm install`
- **Dev server**: `pnpm dev` (port 3000)
- **Reset database**: `pnpm db:reset` (drops, recreates, re-runs `migrations/`)

## Boundaries

- `src/routes/` must not import from `src/repos/`. Routes call services; services call repos.
- `migrations/` is append-only. To change a migration, add a new one.

## Review checklist

- [ ] `pnpm typecheck` passes
- [ ] `pnpm lint` passes with zero warnings
- [ ] The changed endpoint was actually called --- compiling is not verification

**A human verifies these. AI must not claim they are done**: staging smoke test, dashboard visuals.

最后那行是我比较满意的一个设计。有些验收项 AI 根本没法验------预发环境冒烟、看板视觉------那就明确标出来「这条由人验证，AI 不许声称已完成」，免得它在回复里给你打个勾糊弄过去。

这些规则的依据

章节骨架不是我随手定的，是数了 agents.md 官方 showcase 里三个真实项目的章节：apache/airflow（522 行）、openai/codex（322 行）、temporalio/sdk-java（59 行）。

「指令要可验证」「规则不能互相矛盾」来自 Anthropic 的 memory 文档。「指令预算」的说法来自 HumanLayer 的 Writing a Good CLAUDE.md：前沿模型能可靠遵循的指令大约在 150--200 条，超出之后所有指令的遵循率一起下降。

有两条主张是我自己加的，超出了官方文档：

不设固定行数上限。 判断标准是「能不能删掉一行而不损失信息」。根文件超过 200 行，第一反应应该是把内容下沉到子目录的 AGENTS.md，而不是把句子压短。
测试和编码规范不是必备章节。 showcase 的统计里它们出现频率很高，但在一个没有测试框架、没有格式化工具的项目里，这两节只会变成套话。

不同意的话欢迎去仓库开 issue。

入口文件别用软链

项目级的入口文件（CLAUDE.md、GEMINI.md）不要用软链 。提交进 git 的软链，在 Windows 和一部分 CI runner 上会退化成一个内容是路径字符串的普通文本文件。老老实实建一个只有一行 @AGENTS.md 的实体文件。

用户级配置（~/.claude/、~/.codex/）用软链没问题，install.sh 用的就是软链。

另外 Cursor、Cline、Windsurf 的规则文件格式跟 AGENTS.md 不兼容（.mdc 带 frontmatter、.clinerules、global_rules.md），千万别软链过去。

仓库信息

MIT 协议。CI 在 Linux、macOS、Windows 上跑，断言 examples/before.md 退出码为 1、examples/after.md 为 0。改 lint 规则的话 bash 和 PowerShell 两个脚本都要改。

如果你机器上不止一个 agent，装一份就够，不用每个工具复制一遍。