最近我写了一个 agent skillagents-md-writer。它做的事情很简单让 agent 写AGENTS.md的时候先去仓库里探测只写验证过的东西写完自己跑一遍检查。GitHubhttps://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 的规矩想把它们固定下来不用每个项目重新交代一遍。比如这两条是我现在全局配置里最有用的- 本轮改动了文件就在回复末尾列出全部改动文件的**完整路径**标注新增/修改/删除 不要只说「已更新」。 - 需要我拍板的事项一律收在回复最末尾的「待你确认」块编号列出。 每条写成一句话说清问题 → 列 A/B/C 选项及各自代价 → 标出你推荐哪个并说明理由。第一条治「它到底改了什么我得自己翻」第二条治「它自作主张选了一条路还不告诉我有别的选项」。但这两条属于个人偏好换个仓库依然成立所以它们该待在全局配置里不该复制进每个项目的AGENTS.md。这个区分我也写进了 skill它会主动把这类规则往全局挪把「本仓库的提交格式是feat(scope):」这类事实留在项目里。支持哪些 agentskill 本身遵循 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。安装这个 skillhttps://github.com/RUIIIOVO/agents-md-writer自己动手就两条命令gitclone 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 调用它自己认出调用者不弹提示。重复跑不会出错。几个常用参数./scripts/install.sh--all# 本机所有 agent 都链上./scripts/install.sh--agentcodex# 指定一个./scripts/install.sh --dry-run# 只看计划不改东西./scripts/install.sh--where# 输出 agent 和路径两行就退出实体只有一份各 agent 各链一条软链过去。git pull一次所有链上的 agent 都是新的不会分裂成好几份副本。Windows 用scripts/install.ps1建的是目录联接junction不需要管理员权限也不用开发者模式。装完问一句「你现在有哪些 skill」就能确认。三种用法装完之后不用再跑任何命令也不用记 slash command。走哪一条看你怎么说。一、给项目写一份在项目目录里打开 agent直接说给这个项目写一份 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当入口而不是复制两份内容出来各自跑偏。二、检查现有的检查一下我的 AGENTS.md这一条只读不改。它给你一句结论能用 / 要修 / 建议重写加一张位置 → 问题 → 建议的清单。你没点名要改哪个它一个字都不动。也可以直接盘点整台机器检查一下我电脑上所有的 AGENTS.md这里有个细节我写进 skill 了定位文件必须走 Spotlight 索引macOS 的mdfind、Linux 的plocate禁止在 home 目录上做无限制递归扫描。不写死这条agent 很容易一个find ~ -name AGENTS.md下去然后卡在那里。实在没有索引也要求限定目录和-maxdepth。三、整理已经写臃肿的这个 CLAUDE.md 四百行了整理一下这一条会先cp CLAUDE.md CLAUDE.md.bak备份并告诉你备份在哪然后把每一段分类先给你一张表去处什么内容留在项目项目事实目录结构、命令、边界、约定上提到全局个人偏好语言、输出风格、本机环境下沉到子目录只跟某一个模块相关的规则移到 skill多步骤流程、低频的专门知识删除过期内容、元规则、手填日期、一次性需求你过目确认之后它才动手。这一步我特意做成两段式的因为「整理」这个动作删起来没有边界让 AI 自己决定删什么太危险。lint 脚本12 项自检里有 5 项是纯机械的所以单独做成了脚本不依赖 AI 判断检查项级别存在 YAML frontmattererror写死开发机路径/Users/x/、/home/x/、C:\error手填日期YYYY-MM-DDwarning反引号里的路径在磁盘上不存在warning行数超过 200warning./scripts/lint-agents-md.sh# 默认检查 ./AGENTS.md./scripts/lint-agents-md.sh AGENTS.md docs/sub/AGENTS.md pwsh-Filescripts/lint-agents-md.ps1 AGENTS.md# Windows退出码0表示没有 error1表示至少有一个可以直接挂到 CI 上。NO_COLOR1关彩色输出。脚本只依赖 bash 3.2macOS 自带的那个版本、zsh 或 PowerShell 5.1没有外部依赖不用装 node 也不用装 python。两个注意点lint 按被检查文件所在目录解析路径所以要在真实仓库里跑。别拿它检查SKILL.mdskill 文件本来就该有 frontmatter。写出来的东西长什么样摘一段仓库里的样例examples/after.md## 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/airflow522 行、openai/codex322 行、temporalio/sdk-java59 行。「指令要可验证」「规则不能互相矛盾」来自 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装一份就够不用每个工具复制一遍。