agents-md-generator

AGENTS.md 生成器

生成一层精简的指令，其中包含经核实且会实质影响 Agent 行为的项目事实。通用工程知识不应放在始终加载的指令中。

委派

默认在主对话中执行。委派可能增加用量：使用子 Agent 前，先就拟使用的 Agent 数量和范围征得明确批准。在批准范围内可重复使用该授权；若要扩大已批准的数量或范围，则需再次征求批准。

发现指令链

编辑前，检查现有指令、其所有权、作用范围和符号链接。保留可正常使用的共享源文件，例如指向 CLAUDE.md 的 AGENTS.md；不要仅为强制采用偏好的文件名而替换它。只有在所请求的工具支持需要时，才添加兼容文件。处理仓库指令任务时，将全局用户配置留在仓库之外。

对于不熟悉或涉及多种工具的仓库，内置检测器可定位指令路径和已声明的框架／工具信号：

"<skill-directory>/scripts/detect-agent-context" --root "<repository-root>" --format json

在 Windows 上，使用 scripts/detect-agent-context.cmd 并传入相同参数。Python 会提供 JSON；原生 Bash／PowerShell 回退方案会输出较精简的文本报告。相对于此技能定位脚本，而非相对于目标项目。对于已知且范围明确的编辑，直接检查文件即可。

检测器会索引选定的公开清单以及指令／配置路径，不会读取凭据、环境文件或指令内容。将其视为索引：读取适用的指令，并在写入前从源文件核实命令。只有在已获授权且与任务相关时，才纳入全局路径。

若要了解检测器详情，请阅读 discovery.md；若加载顺序和工具支持行为会影响输出，请阅读 tool-compatibility.md。

筛选持久规则

当一条规则不显而易见、有项目证据支持、适用于多种任务且足够具体、便于遵循时，才予以保留。合适的候选内容包括：确切的命令运行器、生成文件的所有权、特殊的业务边界、必需的检查，以及仓库特有的部署或审批限制。

删除或改写通用建议、角色设定、重复规则、过时命令、详尽清单、强制问卷、缺乏依据的评分，以及与当前项目意图冲突的流程。说明实际的授权边界；不要凭空增加新的审批关卡，也不要削弱明确规定的要求。

详细的设计、API、测试和部署指南应保留在原有归属文件中，并附上明确的读取条件。排除机密信息、主目录路径、提示词记录、任务日志和全局工具清单。

编写或协调

默认采用一个精简的共享指令源。只有当目标工具支持且确有实质性的作用范围差异时，才使用嵌套文件，并且不要重复父级规则。对于 Codex，在提出文件布局前，先检查同目录 AGENTS.override.md 的优先级。若需要兼容 Claude，可通过导入或现有符号链接避免重复规则。

将 output-template.md 作为选项参考。把现有内容分类为保留、更新、迁移、删除或待解决；从源文件核实事实，并且只针对需要用户决策的冲突提问。若要整合现有文件，请阅读 merge-and-verify.md。

根目录文件通常控制在约 80–150 行，作用范围更窄的文件则应更短，不要为凑数而填充内容。若根目录文件超过 200 行或 16 KiB，请检查是否存在重复内容或不应放在此处的细节；在遵守目标工具实际加载限制的前提下，保留有充分依据的要求。不要仅为避免编辑而提高全局上下文上限。

使用已跟踪文件的差异进行恢复。保留原本可能丢失的未跟踪内容。不要创建常规备份副本、改写历史，也不要仅仅为了生成指令就忽略整个工具配置目录。

验证

检查引用的路径和命令、范围／优先级、符号链接、重复规则以及未解决的占位符。测量行数／字节数，并确保相关指令链适用于目标工具。适用时运行仓库验证器。静态检查命令不代表已执行该命令；不要为了核实命令拼写而运行破坏性命令。

报告保留、修改、移动或删除的重要规则、所用证据以及尚未解决的冲突。除非用户要求，否则不要单独提交发现报告。