# Init Agents Md

> 基于项目证据创建或更新指定作用域的 AGENTS.md；发现既有匹配指南时，先取得文件选择、合并或覆盖和最终写入确认。

- Skill: `hackycy/init-agents-md` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add hackycy/init-agents-md`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hackycy/init-agents-md/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: hackycy (https://skillmd.com/u/hackycy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hackycy/init-agents-md

---


# Initialize AGENTS.md

为仓库根或一个既有目录创建贡献者指南。输出格式和推荐章节的唯一来源是 [`references/agents-md-prompt.md`](references/agents-md-prompt.md)；本 skill 负责把这份固定指令安全地应用到正确的作用域。

## 输入与作用域

- 接受零或一个目录参数，相对路径按当前工作目录解析。无参数时使用 `git rev-parse --show-toplevel` 找到的 Git 根目录。
- 显式目录可以不在 Git 仓库中；无参数且找不到 Git 根时，要求用户指定目录并停止。路径必须解析为可读目录；缺失路径、文件、不可读目录或多个目录参数都停止。
- 默认候选输出为该目录的 `AGENTS.md`。一次只处理一个作用域，不创建目录，不改动其他文件，不暂存、提交或创建分支。
- 正文跟随本地文档主语言；信号不足时使用英文。若选定目录不是仓库根，输出在开头加入 `## Scope`，说明相对目录和适用父级指南，只写本地新增或收窄规则。

## 先侦察，再生成

1. 在起草前读取目标和必要的项目上下文：目录结构、manifest/lockfile、脚本、构建/测试/lint 配置、CI、README/CONTRIBUTING，以及 Git 可用时最多 30 条相关提交。识别 monorepo 包边界、包管理器和本地文档主语言。
2. 找出所有相关 `AGENTS.md`：目标文件、从仓库根到目标父目录的祖先文件，以及目标子树中的嵌套文件。对非 Git 目录，按祖先链检查。子树先检查直接子目录，只在 manifest、包边界或已有指南指向更深层时扩展；跳过 `.git`、依赖/vendor、构建/coverage 输出、缓存和被忽略的秘密存储。
3. 将匹配项标为 `target`、`ancestor` 或 `nested`，并读取 `CLAUDE.md`、`CONTRIBUTING.md` 等相关指南作为约束。嵌套指南只读取、保留，必要时链接；不合并或修改它们。
4. 仅检查潜在秘密文件的名称和元数据。绝不读取或写入密钥、token、凭据或 `.env` 内容。
5. 每个命令和约定必须能由脚本、配置、已有文件或历史验证。区分观察到的仓库规则和通用默认建议；没有证据的章节、命令或断言直接省略。

## 匹配指南确认

在生成草稿前，展示所有匹配项、各自作用域和候选输出路径，并检查大小写冲突（例如 `agents.md`）。这是一道硬门槛：

- 候选目标已存在时，读取它并要求用户选择 `merge`、`replace` 或 `abort`。
- 目标不存在但发现祖先或嵌套指南时，要求用户明确选择“创建该作用域的新指南”或“更新某个命名的现有指南”；不得静默新增子级文件。若选择其他现有文件，按该文件目录重新侦察后再选择模式。
- 没有匹配项时，继续为原目标起草新文件。
- 选中的 `AGENTS.md` 是符号链接、目录、特殊文件或不可写普通文件时停止并报告原因。

任何未回答、含糊的选择或与 `CLAUDE.md` 等指南的冲突，都保持工作区不变。

## 读取固定指令

在开始起草前完整读取 [`references/agents-md-prompt.md`](references/agents-md-prompt.md)。它是标题、文档要求、推荐章节、字数目标和表达风格的 canonical owner；正常运行时不改写它，也不要在本 skill 中复制它的正文。
## 合并、预览与写入

`merge` 按 Markdown 标题语义合并：保留既有事实和自定义章节，只补入缺失且有证据的内容。把全部命令、路径、优先级或事实冲突列成一张表，让用户逐项选择保留现有、采用证据或提供自定义文本；存在未决冲突时不得写入。`replace` 只影响选中的单个文件，不自动生成备份。

新文件展示完整草稿；更新展示 unified diff，并附路径、作用域、章节、字数、证据缺口和模式摘要。用户明确确认最终写入前不创建或修改文件；要求修改则回到起草和预览。写入前重新读取目标，若内容已被外部改动，重新走确认流程。

## 校验与完成

写入前检查标题、标题层级、嵌套指南的作用域链接、引用的路径/脚本、占位符、敏感值和 Markdown 空白；根指南按固定指令的字数目标检查，嵌套增量按约 100-300 词检查。只自动修复尾随空格、重复空行等机械问题，并再次预览；语义或事实问题交给用户决定。目标在 Git 中时运行 `git diff --check`，否则做等价空白检查；不要为本 skill 默认运行完整 build、test 或 lint。

完成条件：已确认的 `AGENTS.md` 在选定路径存在、通过静态检查、与批准的预览一致；最终报告模式、作用域、已验证命令、遗漏/不确定项和校验结果。用户 `abort` 或校验无法通过时，报告原因并保持目标不变。