Agents Md Expert

AGENTS.md Expert

工作模式

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

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

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

核心约束

• 只写来自仓库、适用上级指令或用户确认的事实，不虚构命令和团队政策。
• 只保留会改变 Agent 行为的内容，不复制 README 中的一般介绍。
• 尊重宿主定义的指令优先级和作用域；子级文件只补充必要差异。
• 必须加入防漂移规则：项目结构、技术栈、命令或开发约束变化时，在同一变更中同步更新适用作用域的 AGENTS.md。
• 不读取或写入密钥，不把用户私有路径、临时状态或机器特征固化到文件中。
• 不覆盖用户已有改动，不用重置、清理或删除操作修复验证副作用。

执行流程

1. 确定目标

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

2. 只读调查

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

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

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

3. 处理不确定性

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

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

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

4. 创建或改进

按需选择章节，不机械套用全部标题：

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

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

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

5. 审查

Review 模式先按严重级别报告问题，再给修复建议。重点检查真实性、作用域冲突、命令有效性、模糊规则、重复内容、私有信息和危险操作。使用 [references/review-rubric.md](references/review-rubric.md)。

6. 验证

将 [scripts/auditagentsmd.py](scripts/auditagentsmd.py) 解析为相对本 Skill 目录的路径并运行：

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

自动运行仓库已声明且确认无破坏性的格式检查、静态分析或测试。无破坏性表示不会安装依赖、修改受版本控制文件、变更 Git 历史、访问发布环境或写入持久业务数据。

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

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

完成报告

报告：

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: betterlmy
• Source: betterlmy/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.