Initialize AGENTS.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。它是标题、文档要求、推荐章节、字数目标和表达风格的 canonical owner；正常运行时不改写它，也不要在本 skill 中复制它的正文。

合并、预览与写入

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

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

校验与完成

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

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