SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场agents-md

agents-md

智能体与模型

查看项目

更新于 10-16 04:37

技能介绍

用途

agents-md 是一个用于审计与重构仓库 AGENTS.md 的技能，目标是让智能体能够真正依据该文件行动。当用户要求审计 AGENTS.md、修复 AGENTS.md、搭建或改进智能体文档时使用。

其出发点是：AGENTS.md 的每一行都会在每次任务中被加载，因此冗余会挤占项目专属规则所需的预算，矛盾会互相静默覆盖，默认行为条目会稀释真正能引导模型的规则。核心原则是：AGENTS.md 中的每一行都必须是项目专属的；如果一个有能力的模型在没有该行的情况下也会做对，就删除它。根文件是一张地图，深度内容存在于 README.md、docs/ 与 references/。

规范语言

常规工作流指令使用简单祈使句。MUST / MUST NOT 仅保留给具有明确失败模式的硬性约束，SHOULD 用于在可解释偏离情况下仍成立的强默认项。不要求每条规则都以 RFC 2119 关键词开头，关键词通胀会掩盖真正重要的规则。

工作流程

  1. 发现矛盾：列出每一对矛盾，提出应保留的版本并给出一句理由，询问用户，绝不自动裁决。矛盾编码了模型看不到的用户选择，自动裁决等于暗中选边。

  2. 识别根文件必备内容。AGENTS.md 中仅保留：一句话项目描述；指向更深入的项目概览、架构、安装与工作流文档的真相来源指针；包管理器（仅当不是 npm 时）；非标准的 build / test / lint / typecheck 命令；Forbidden Patterns 表；边界（never X 规则）；验证命令；References 表。

  3. 分诊冗余：标记每一处实例，各类模式的具体前后对照片段见 references/anti-patterns.md。包括：默认行为条目（如“write clean code”“meaningful names”、通用 ARIA）应删除；模糊限定词（“try to”“ideally”“consider”“might want to”）改写成祈使句；元前缀（“You should”“Remember to”“Please”）应剥离；跨章节重复（同一命令出现在 2 个以上 H2 章节）保留最具体的位置；硬编码清单（组件列表、依赖版本）替换为 ls / find / 运行时命令；内联理由（每条规则写“Use X because A, B, C”）把理由移到 ADR；零价值章节（完全被另一章节覆盖）删除；README 重复内容（项目概览、安装、用法、架构导览、包/分发细节）在 AGENTS.md 中保留一行身份说明并指向 README.md；过期路径经核实后修复或移除。

  4. 对其余内容分组：README.md 承载面向人的项目概览、安装/用法、包或分发模型与总体架构导览；docs/adr/ 承载非显而易见的架构决策；docs/conventions.md 承载超出语言默认值的项目专属惯用法；docs/workflow.md 承载分支/提交/PR 循环与确切命令；references/<topic>.md 承载目录（tokens、API 表面、图标）与理由集合。

  5. 提出文件结构：最小化的根 AGENTS.md，底部带 References 表；每个主题文件及其内容；建议的文件夹布局。产出 diff 计划，不应用编辑。

何时跳过重构

AGENTS.md 缺失或少于 20 行：先从 references/templates.md 生成，再审计；拆分空文件只会产生空文件。纯样板（无项目专属内容）：先填写技术栈/命令/结构；拆分样板不会使其有用。含多个包清单的 monorepo：审计根文件，然后为惯例不同的包推荐各自的 AGENTS.md。已经是带 References 表的 100–200 行地图：只运行最终检查，不要重构已经正确的文件。

最终检查

产出计划前，以下各项必须为真。

提出 1–3 个 docs/adr/ 中的 ADR，仅当四项全部成立：难以逆转、脱离上下文时令人意外、是真实取舍的结果、所述理由在技术上准确。把生态主张（关于框架/版本/API 的“X requires Y”）写进 ADR 前先核实。跳过显而易见的选择。被奉为 ADR 的错误理由会毒害未来每一次智能体运行。

编写 Forbidden Patterns 表：项目实际犯下的每个错误一行，列包括 WRONG、CORRECT、Why，不编造示例。

列出 3–7 条边界（never X 规则），覆盖项目真实的事故面；超过七条模型会开始忽略。

指定验证命令：每次更改后运行的确切 CLI 调用。

在 AGENTS.md 底部构建 References 表，每一行都指向磁盘上存在的文档。当 README.md 承担定位职责时引用它：如果 README.md 说明了仓库是什么、如何安装或用户如何消费，就把它列入 References，而不是重复其内容。

核实磁盘路径：对 AGENTS.md 中提到的每个路径执行 test -e <path>，任何未命中都是过期链接。

用 ls、find 或运行时命令替换硬编码清单，静态列表会过期。

建立符号链接 CLAUDE.md → AGENTS.md。缺失时执行 ln -s AGENTS.md CLAUDE.md；若为常规文件，先把任何独有内容合并进 AGENTS.md，再执行 rm CLAUDE.md && ln -s AGENTS.md CLAUDE.md；若已是指向 AGENTS.md 的符号链接，跳过。

阅读内容而不仅是结构，进行三次具体检查：列出清单章节中每个具名实体（组件、脚本、token、依赖）并检查重复；把所述工具链与实际技术栈交叉比对（若 Stack 写 Vite 而 build 运行 tsup，则其中之一有误）；把生态主张当作约束前先核实（在当前版本下 Y 是否真的需要 X），假装成事实的错误理由比没有理由更糟。

常见辩解

“这个矛盾很明显，我直接裁决”——两个版本同时存在是因为有人持不同意见，应询问。“默认行为条目留着更安全”——它们挤占了真正引导模型的规则槽位，应删除。“先写模板让用户挑”——先调研再生成，没有调研的模板产出的是通用 AGENTS.md，不是本项目的。“边读边重构”——先调研，再计划，后应用，边读边重构会产生不一致的结构。“跳过路径核实，看起来是对的”——一个过期路径会静默误导未来每一次智能体运行，必须核实。“通用的可访问性/安全/‘clean code’规则可以保留”——它们属于默认行为，保留只会稀释那些非默认的规则。

交付前验证

对拟交付用户的计划运行以下验证：以对仓库一无所知的视角重读新的 AGENTS.md，能否仅用该文件执行一个真实任务？若不能，文件仍不够具体。对 AGENTS.md 中每条 CLI 命令 grep 该文件，若出现在 2 个以上 H2 章节则说明重复。对每个路径执行 test -e，未命中即过期链接。

参考资料

references/anti-patterns.md — 当第 3 步标记某个模式且需要具体前后对照时加载。 references/templates.md — 当需要从零生成新的 AGENTS.md、ADR、conventions.md 或 workflow.md 时加载。

底线

AGENTS.md 根文件 → 项目专属规则、已核实路径、用运行时发现替代清单；其他一切 → docs/ 或 references/ 或删除。如果某一行可能出现在任何项目的 AGENTS.md 中，它就不属于本项目。

限制

该技能只产出 diff 计划与结构建议，不直接应用编辑。关于具体收费、价格、支持平台与效果，资料中暂未提供。