用途
review-agents-md 用于创建和重构 AGENTS.md 文件，遵循渐进式披露（progressive disclosure）原则，使文件保持最小、聚焦，避免出现损害智能体性能的「一团泥」（ball of mud）。适用的场景包括：项目根目录尚无 AGENTS.md 时主动检查并建议创建；从零创建新的 AGENTS.md；重构臃肿的 AGENTS.md；按最佳实践审查现有文件；为 monorepo 设置 AGENTS.md；以及 AGENTS.md 已存在但缺少应作为符号链接的 CLAUDE.md 时。
核心原则
- 默认最小化：只包含与每一个任务都相关的内容。
- 渐进式披露：将领域特定规则指向独立文件、外部文档或 agent skills。
- 绝不记录文件结构：文件结构很快过时，并会污染智能体上下文。
- 描述能力而非位置：写「Auth uses JWT」，而不是「Auth is in src/auth/」。
指令预算
前沿 LLM 大约能较为一致地遵循 150–200 条指令。AGENTS.md 中的每一个 token 都会在每次请求时加载，不论是否相关，因此理想文件应尽可能小。
文件为什么会臃肿：智能体做错事 → 你加一条规则 → 重复数百次 → 形成「一团泥」。不同开发者加入相互冲突的观点，没有人做完整的风格梳理。自动生成的文件会更糟，因为它们优先考虑全面而非克制。
过时文档会毒化上下文：人可以怀疑过时文档，但智能体不会——它们信任每次请求读到的内容。文件路径尤其危险，因为它们经常变化，因此应描述能力与领域概念。
处理流程
阶段 0：检测缺失文件
检查项目根目录的 AGENTS.md 和 CLAUDE.md：
- 两者都不存在：建议创建 AGENTS.md，并将 CLAUDE.md 符号链接到它。
- AGENTS.md 存在但 CLAUDE.md 不存在：创建符号链接
ln -s AGENTS.md CLAUDE.md。 - CLAUDE.md 存在但 AGENTS.md 不存在：重命名并创建符号链接
mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md。 - 两者都存在但 CLAUDE.md 不是指向 AGENTS.md 的符号链接：将独有内容合并进 AGENTS.md，删除独立的 CLAUDE.md，再创建符号链接。
阶段 1：评估当前状态
新项目：询问项目用途（一句话）、包管理器（若不是 npm）、非标准构建命令。
已有文件：阅读当前 AGENTS.md，统计行数并估算 token 成本，识别应移到别处的内容。
阶段 2：套用「必要测试」
只有以下内容属于根 AGENTS.md：
- 一句话项目描述（锚定每个智能体决策）
- 包管理器（如果不是 npm，防止用错命令）
- 非标准的构建/测试命令（省去试错）
- 指向领域特定文档的链接（渐进式披露）
其余内容都应放入独立文件或删除。
阶段 3：识别反模式
以下内容应被标记为删除或迁移：文件树结构（必然过时、浪费 token）；显而易见的要求（如「Write clean code」「Use meaningful names」）；相互矛盾的规则（常来自多位贡献者）；语言特定约定（移到 docs/TYPESCRIPT.md 等）；工作流说明（移到 docs/GIT.md 或 docs/TESTING.md）。
阶段 4：建立渐进式披露结构
对于不应删除的内容：
docs/ ├── TYPESCRIPT.md # TS conventions ├── TESTING.md # Test patterns ├── API.md # API design rules └── GIT.md # Commit/PR conventions
在 AGENTS.md 中用轻量指针引用它们，语气保持对话式——不要用「ALWAYS」，不要用全大写强制：
For TypeScript conventions, see docs/TYPESCRIPT.md
每个文件可以再引用下一个——智能体按需沿树查找，只加载相关内容。当外部文档是权威来源时，直接链接而不复述，例如：For database migrations, follow the Prisma migration guide.
Agent skills 是另一层渐进式披露。与其把流程嵌入 AGENTS.md，不如打包为技能，由智能体在需要时拉取。根文件专注于 what 和 where，技能负责 how。
阶段 5：处理 Monorepo
Monorepo 使用嵌套的 AGENTS.md。根 AGENTS.md 示例：
Monorepo for [purpose]. Uses [pnpm/yarn] workspaces. See each package's AGENTS.md for specifics.
包级 AGENTS.md（如 packages/api/AGENTS.md）示例：
GraphQL API using Prisma. See docs/API_CONVENTIONS.md for patterns.
阶段 6：输出
提供新/重构后的 AGENTS.md 内容、为渐进式披露新建的文件、以及被移除内容及其理由的清单。
输出格式
创建新 AGENTS.md 时：
[Project Name]
[One-sentence description of what this project does.]
[Package manager if not npm]
[Non-standard commands if any]
[Light-touch pointers to separate docs if needed]
最小 AGENTS.md 示例：
Acme Dashboard
React admin dashboard for managing customer accounts and billing.
Uses pnpm. Run pnpm check for type checking.
For API conventions, see docs/API.md For component patterns, see docs/COMPONENTS.md
共 6 行，每个 token 都物有所值。
重构提示
重构已臃肿的文件时按以下步骤：找出矛盾（识别冲突指令并确认保留哪条）；识别必要项（只提取属于根目录的内容）；对其余内容分组（组织为逻辑类别并创建独立文件）；建立结构（输出最小根 AGENTS.md 并链接到独立文件）；标记删除（识别冗余、模糊或显然的指令）。
决策框架
加入 AGENTS.md 之前先判断位置：与每一个任务都相关 → 根 AGENTS.md；只与一个领域相关 → 独立文件；适合层级组织 → 嵌套文档；显然、冗余或模糊 → 删除。
跨工具兼容
AGENTS.md 是开放标准，受 20 多种工具支持，包括 GitHub Copilot (Coding Agent)、Cursor、Codex (OpenAI)、Gemini CLI (Google)、Windsurf、Devin (Cognition)、Zed、Warp、VS Code、Aider、goose、RooCode。Claude Code 使用 CLAUDE.md。AGENTS.md 始终是唯一事实来源，CLAUDE.md 必须始终是指向它的符号链接：
ln -s AGENTS.md CLAUDE.md
绝不创建独立的 CLAUDE.md。绝不把不在 AGENTS.md 中的内容放进 CLAUDE.md。
资源
https://agents.md — AGENTS.md 规范
https://www.aihero.dev/a-complete-guide-to-agents-md — 为本技能最佳实践提供参考的指南
限制
未提供该技能的计费、价格、具体平台可用性（如是否可在某商店安装）等信息。