agents-md

agents-md

面向仓库的 AGENTS.md 卫生检查：创建文件、测量、审查内容，并与其在各工具环境中的镜像文件核对。单一规范文件，与工具环境无关，不含 frontmatter。

.github/copilot-instructions.md 的编写和 Copilot 代码审查配置 位于 /github-copilot-repo-instructions（如果已安装）。此技能只会 检查该文件与 AGENTS.md 的镜像状态；不会编写 Copilot 专属内容或 applyTo 路径规则。

个人或机器全局指令文件（用户自己的 ~/.claude/CLAUDE.md、 个人 Copilot 指令）不在范围内。此技能只会处理 已提交到仓库的文件。

---

为什么 AGENTS.md 卫生检查很重要

AGENTS.md 是一种厂商中立的纯 Markdown 约定，没有必填字段 （agents.md）。各工具环境会在不同时间加载适用文件。加载的文本会占用上下文，因此请保持指令简洁、命令及时更新。不要将加载的上下文等同于计费 token，也不要假设每个文件都会在每轮对话中加载。

关于有效性的证据并不一致。保留有助于 Agent 行动的仓库规则， 不要保留基于任务成功率承诺的规则。加载行为请参阅 references/harness-matrix.md，研究局限请参阅 references/content-checklist.md。

---

协议

1. 清点指令文件

列出仓库中现有的文件，使用相对于仓库的路径，包括根目录和嵌套目录：

find . -maxdepth 4 \( -name AGENTS.md -o -name CLAUDE.md -o -name CLAUDE.local.md \
  -o -name GEMINI.md -o -path '*/.github/copilot-instructions.md' -o -path '*/.cursor/rules*' \) \
  -not -path '*/node_modules/*'

每种工具环境读取的文件子集、优先级和上限各不相同。 在假设某个文件的存在或缺失等同于另一个文件之前，请先阅读 references/harness-matrix.md——最近文件优先是常见规则（agents.md 规范、Codex、Copilot、Cursor），但 Claude Code 有不同的触发条件：只有当工作文件上方不存在 CLAUDE.md/CLAUDE.local.md 时，它才会读取 AGENTS.md；或者通过 CLAUDE.md 中显式的 @AGENTS.md 导入来读取。

2. 测量

python3 "$AGENTS_MD_CHECK" [path/to/AGENTS.md]

从已加载的 SKILL.md 所在目录解析 AGENTS_MD_CHECK （scripts/agents_md_check.py），先解析符号链接。不要假设目标仓库中的技能位于 skills/agents-md/。

报告字节数、行数、标题映射、每个引用的 just <recipe> 是否能在附近的 justfile 中找到、每个引用的仓库相对路径，以及 CLAUDE.md、.github/copilot-instructions.md 和 GEMINI.md 的镜像状态。文件超过约 200 行时，会发出软性可读性警告。该脚本还会汇总从仓库根目录到被检查文件所在目录及其下级目录的 AGENTS.md 链。链超过 32 KiB 时会直接失败。OpenAI Codex 会从根目录向下拼接该链。当总大小达到 project_doc_max_bytes（默认 32 KiB）时，它会停止添加文件，因此最靠近工作目录的文件会最先被舍弃 （https://developers.openai.com/codex/guides/agents-md/）。

根目录发现和跳过规则遵循 Codex：

• 根目录是被检查文件所在目录或其上级目录中最近的、包含 .git 的目录。若没有 .git，每条链仅包含被检查文件，报告会用“文件目录”代替“仓库根目录”。
• 对每个目录，如果存在 AGENTS.override.md，则使用它；否则使用 AGENTS.md。
• 大小按磁盘上的原始字节计算，因此 CRLF 行尾会完整计入。
• 遍历时会跳过点目录、node_modules、失效符号链接，以及包含自身 .git 的任何子目录（嵌套项目根目录）。

退出码：未超过任何链上限、没有镜像分歧，且所有引用的配方和路径均存在时返回 0。超过上限、存在任何偏差（镜像分歧、配方缺失或路径缺失），或文件不存在时返回 1。

--json 会输出以下字段：path、bytes、chain_bytes、chain_dir（最大链中最深的目录，相对于根目录）、root_marker（找到 .git 根目录时为 true）、lines、byte_cap、cap_breach、near_cap、line_warn、headings、justfile、referenced_just_recipes、missing_recipes、referenced_paths、missing_paths、mirrors、diverged_mirrors 和 drift。

3. 内容审查

对于 AGENTS.md 中提到的每条命令和路径，都要对照实际仓库核验，而不是凭记忆判断：

• 每个反引号中的 just <recipe> 都必须存在于 justfile 中——脚本会检查这一点；将 FAIL missing just recipes 行视为过时命令，而不是脚本错误。
• 每个反引号中的仓库相对路径都必须存在——同样处理 FAIL missing referenced paths。
• 质量门禁、约定和“不要改动”的边界必须符合项目实际的 CI 和审查流程，而不是理想化的设想。
• PR 和提交规则必须明确写出，不能只暗示。

根据 references/content-checklist.md，标记并移除以下反模式：叙述性历史、README 内容重复、机密或令牌、个人偏好，以及已无法运行的命令。

4. 镜像策略

仅保留一个规范的 AGENTS.md。对于每个镜像：

• CLAUDE.md：要么不存在，要么只包含 @AGENTS.md（Claude Code 导入——https://code.claude.com/docs/en/memory）。不要在其中重复内容。
• .github/copilot-instructions.md：要么不存在（Copilot 会直接读取 AGENTS.md），要么只包含简短指引。如果用户需要 Copilot 专属内容（路径范围内的 applyTo 规则、代码审查设置），请转到 /github-copilot-repo-instructions——不要在此处编写该文件。
• GEMINI.md：要么不存在，要么遵循与 CLAUDE.md 相同的模式，提供简短指引。

将检查脚本标记为 diverged 的任何镜像报告为偏离，并建议将其精简为指引文件或删除。

5. 嵌套 AGENTS.md

对于单体仓库或多包布局，在每个需要独立规则的包中放置一个嵌套的 AGENTS.md。Codex、Claude Code、Cursor、Gemini CLI 和 Copilot CLI 会同时加载嵌套文件及其所有上级文件。没有任何工具会用嵌套文件替代根文件。只有发生冲突时，距离更近的文件才优先。各工具的具体行为见 references/harness-matrix.md。

• 嵌套文件中只放该子树特有的内容：其专属命令、边界和例外。复制根规则会在两个文件同时加载时造成上下文重复，也可能导致内容偏离。
• 明确说明每项针对根规则的例外，并指出被替代的根规则。VS Code 会提醒，各工具的优先级顺序并不统一。
• 每条从根目录到叶目录的文件链都必须低于 Codex 的 32 KiB 上限。Codex 会优先丢弃距离最近的文件。
• 只有在该目录没有自己的 CLAUDE.md 时，Claude Code 才会读取嵌套的 AGENTS.md。

6. 精简或重写

始终以当前文件为基准，使用差异形式展示拟议变更。然后停止，并在写入 AGENTS.md 或任何镜像前征求明确批准。要求跳过差异（“我不需要看差异”）不代表可以跳过此步骤，也不构成批准。只有在用户批准你展示的差异后，才能写入。

绝不要运行 git commit 或 git push。将变更保留在工作树中。提交由用户负责。

新建文件时，以 assets/AGENTS.md.template 作为结构起点，而不是未经修改地复制粘贴为模板——每个部分都必须反映该仓库的实际命令和边界。

7. 验证

python3 "$AGENTS_MD_CHECK" --self-test
python3 "$AGENTS_MD_CHECK"

两条命令都必须以状态码 0 退出。审查过程中修改或新增的任何命令，都必须在报告完成前重新运行。

---

规则

• 每个目录作用域只能有一个规范的 AGENTS.md。镜像文件指向它，不重复其内容。
• 切勿编造命令或路径。每个反引号中的 just <recipe> 和每个引用的路径都必须存在——检查脚本会验证这一点，不要跳过检查。
• 不要添加叙述性内容、README 重复内容、机密信息或个人偏好。完整清单见 references/content-checklist.md。
• .github/copilot-instructions.md 中只能添加简短的指引，不得编写其他内容——这类编写工作应交由 /github-copilot-repo-instructions。
• 不要修改个人或机器级别的全局指令文件。
• 覆盖现有的 AGENTS.md 或镜像文件之前，先展示差异并获得明确批准。要求跳过差异不代表已获批准。
• 切勿运行 git commit、git push 或任何其他发布命令。将更改保留在工作树中。

参考资料

• references/harness-matrix.md — 各类 harness 会读取哪些文件，以及优先级和大小上限；已注明引用来源。
• references/content-checklist.md — 说明哪些内容适合放入 AGENTS.md，哪些不适合。有关 harness 行为的说法均附有引用来源；清单内容属于本技能的指导。
• assets/AGENTS.md.template — 简短的分节起始模板。