AGENTS.md Expert

工作模式

先判断任务属于哪种模式：

1. Create：目标作用域没有 AGENTS.md，需要创建。
2. Review：只审查现有文件；除非用户明确要求，否则不要修改。
3. Improve：基于仓库事实修正、精简或补全现有文件。

本 Skill 不用于编写普通 README、贡献指南或完整架构文档。

审计对象与授权

• 先区分仓库入口、用户全局规则和参考资料；全局规则不用填项目技术栈，参考资料不套仓库章节与行数模板。
• 当前任务已授权改进时完成必要修改与验证，不在每个步骤重复确认；范围外副作用仍须授权。
• 脚本默认 --scope repository；用户全局或 Pi 全局用 --scope global，技能内参考手册用 --scope reference。作用域按用途选择，不为了通过检查改变类型。
• 对生效指令同时检查字节体积；超过 16 KiB 会告警，不能靠压缩为长行规避上下文预算。

核心约束

• 只写来自仓库、适用上级指令或用户确认的事实，不虚构命令和团队政策。
• 只保留会改变 Agent 行为的内容，不复制 README 中的一般介绍。
• 每个仓库级 AGENTS.md 至少包含“仓库定位”“技术栈”“目录结构”“文档索引”和“Skill 索引”五个独立章节；其他章节按仓库实际情况选择。
• AGENTS.md 不得超过 240 行；超过上限时必须精简内容，而不是仅记录为可接受的警告。
• 尊重宿主定义的指令优先级和作用域；子级文件只补充必要差异。
• 必须加入防漂移规则：项目结构、技术栈、命令或开发约束变化时，在同一变更中同步更新适用作用域的 AGENTS.md。
• 不读取或写入密钥，不把用户私有路径、临时状态或机器特征固化到文件中。
• 不覆盖用户已有改动，不用重置、清理或删除操作修复验证副作用。

执行流程

1. 确定目标

确认仓库、目标文件路径、适用目录和工作模式。查找适用的上级、当前及子级 AGENTS.md；宿主未定义继承语义时，不自行假定覆盖规则。

2. 只读调查

读取完成任务所需的最小上下文：

• 项目入口文档与架构索引；
• 依赖清单、构建文件、任务脚本和 CI 配置；
• 格式化、Lint、测试、生成代码和迁移配置；
• 贡献规范及关键目录中的局部说明。

优先从受版本控制的文件取证，不扫描 .env、凭据目录或无关的大文件。将候选命令追溯到实际配置，记录其适用目录和副作用。详细方法见 references/discovery-guide.md。

3. 处理不确定性

能从仓库可靠确认的事项直接采用。以下事项无法确认且会改变结果时再询问用户：

• 指令作用域或目标宿主；
• 权威命令存在冲突；
• 是否新增团队政策或高风险限制；
• 是否允许有副作用的验证。

不要为了填满模板而提问，也不要把未知事项写成事实。

4. 创建或改进

以下五个章节是每个仓库级 AGENTS.md 的最低结构，标题可以使用等价的中英文表达，但内容必须分别说明对应事项：

• 仓库定位：项目用途、边界和 Agent 当前负责的仓库范围；
• 技术栈：从仓库事实确认的语言、框架、构建工具和关键运行时；
• 目录结构：影响定位、修改和验证的关键目录；
• 文档索引：仓库内对开发有约束或参考价值的文档及其路径；
• Skill 索引：仓库内可用 Skill、Skill 目录或相关使用入口及其路径。

在最低结构之外，按需选择章节，不机械套用全部标题：

• 作用域和优先级；
• 项目关键结构；
• 修改前工作流；
• 项目特有编码规则；
• 精确的构建、测试和检查命令；
• 生成文件、迁移、兼容性及依赖边界；
• 完成标准和结果汇报。

无论如何组织章节，都必须明确要求：改变项目结构、技术栈、构建或测试命令、开发约束时，同步更新对应作用域的 AGENTS.md，且不得把不相关的上级或子级文件一并改写。

使用“必须”“不要”“仅在……时”等可判定措辞，并说明命令在哪个目录执行。内容取舍和示例见 references/content-model.md。

5. 审查

Review 模式先按严重级别报告问题，再给修复建议。重点检查真实性、作用域冲突、命令有效性、模糊规则、重复内容、私有信息和危险操作。使用 references/review-rubric.md。 按对象类型检查章节、行数和字节预算；不要给用户全局文件补空的仓库章节。

6. 验证

将 scripts/audit_agents_md.py 解析为相对本 Skill 目录的路径并运行：

python3 /path/to/skill/scripts/audit_agents_md.py /path/to/AGENTS.md

自动运行仓库已声明且确认无破坏性的格式检查、静态分析或测试。无破坏性表示不会安装依赖、修改受版本控制文件、变更 Git 历史、访问发布环境或写入持久业务数据。 仓库模式将缺少最低章节或超过 240 行报告为失败；global 保留安全和长度检查，reference 保留安全检查。

运行前后比较工作区状态；若命令产生非预期改动，立即停止并报告，绝不擅自回滚用户文件。命令副作用不明确、依赖缺失或需要外部服务时，先征得用户同意。

最后检查本次改动是否改变项目结构、技术栈、命令或开发约束；若改变，确认适用作用域的 AGENTS.md 已在同一变更中同步更新。

完成报告

报告：

• Skill 模式及目标文件；
• 创建、修改或审查的内容；
• 作为依据读取的关键文件；
• 自动审计与项目命令的结果；
• 未验证事项、假设和剩余风险。