init-agents-md Skill

概述

此 skill 用于在项目根目录生成 AGENTS.md 入口文件和 docs/ 最小骨架，建立面向 agent 的文档治理体系。

核心设计原则来自 OpenAI Harness Engineering 实践：

• AGENTS.md 是目录，不是百科全书：~100 行的入口，指向 docs/ 中的深层真相
• 仓库是知识的系统性记录：Agent 看不到的东西对它等同于不存在
• 渐进式披露：从最小骨架开始，文档随项目复杂度按需创建
• INDEX.md 是导航层：每个目录必须有 INDEX.md，Agent 通过逐层读取索引检索文档，而非扫描目录树

使用方式

在项目中执行：

/init-agents-md

工作流程

1. 检查项目根目录是否已存在 AGENTS.md
2. 如果存在 → 提示用户选择覆盖或跳过
3. 如果不存在 → 写入 AGENTS.md 模板 + 创建最小 docs/ 骨架
4. 显示成功消息，提示用户填写 [待填写] 占位内容

---

AGENTS.md 模板

# AGENTS.md

> 此文件是 AI 在本仓库工作的**入口地图**，保持精简（<100 行）。
> 原则：目录，不是百科全书。Agent 看不到的东西对它等同于不存在。

## 文档检索方式

所有文档通过逐层 INDEX.md 导航，禁止扫描目录树：

AGENTS.md └─ docs/INDEX.md ├─ docs/design-docs/INDEX.md → 具体设计文档 └─ docs/usage/INDEX.md → 使用指南

从 `docs/INDEX.md` 开始检索。

## 仓库结构

[项目维护者在此描述关键目录和模块]

## 编码规范与黄金原则

[项目维护者在此添加技术栈相关规范]

## 文档治理

### 人工审批规则
- **禁止自主创建**：AI 不得自行创建任何文档或目录，必须先请求人工批准
- **禁止自主修改**：AI 修改文档前必须说明修改内容和原因，获得人工同意

### INDEX.md 规则（强制）
- 每个 `docs/` 下的子目录**必须**有 `INDEX.md`
- `INDEX.md` 只做导航：文件名 + 一句话描述，严禁放实际内容
- 新建子目录时必须同步创建该目录的 `INDEX.md`，并更新父级 `INDEX.md`
- 没有 `INDEX.md` 的目录对 Agent 等同于不存在

### 渐进式文档策略
- 项目初期只维护 `AGENTS.md` 和 `docs/INDEX.md`
- 需要新文档时：AI 提出请求 → 人工审批 → AI 创建文档 + 更新对应 INDEX.md
- 空索引是正常的，文档应在真正需要时才创建

---

初始生成的最小骨架

执行此 skill 时，只生成以下最小结构：

AGENTS.md
docs/
└── INDEX.md

docs/INDEX.md 初始内容：

# docs/INDEX.md

> 此目录是项目知识库。通过此文件导航，禁止扫描目录树。
> 每个子目录有独立的 INDEX.md，按需递进查阅。

## 当前文档

| 路径 | 描述 |
|------|------|
| *(暂无子目录)* | |

## 待创建文档（按需触发）

| 目录/文件 | 触发条件 |
|-----------|---------|
| `design-docs/` | 有正式设计决策需要记录时 |
| `usage/` | 有需要向用户或 Agent 说明的使用规范时 |
| `ARCHITECTURE.md` | 项目有超过 3 个明确模块边界时 |
| `DESIGN.md` | 有核心信念和设计原则需要固化时 |
| `QUALITY.md` | 项目引入 CI 且需要追踪质量分时 |

---

渐进式扩展规范

新建子目录时的强制步骤

1. 在目标路径创建 INDEX.md（使用下方模板）
2. 在父级 INDEX.md 的"当前文档"表格中新增一行
3. 将该目录从父级"待创建"表格移除（若存在）

INDEX.md 模板（通用）

# [目录名]/INDEX.md

> 一句话描述本目录的用途。

## 当前文档

| 文件 | 描述 |
|------|------|
| [文件名.md](文件名.md) | 一句话描述 |

## 待创建文档（按需触发）

| 文件 | 触发条件 |
|------|---------|
| *(暂无)* | |

INDEX.md 写作规则

• 只做导航：文件名 + 一句话描述，不放任何实际内容
• 保持精简：每行描述不超过 20 字
• 及时更新：新增/删除文档时必须同步更新 INDEX.md
• 触发条件：未创建的文档必须注明触发条件，不留空占位

---

实现细节

写入顺序

1. 写入 AGENTS.md
2. 创建 docs/ 目录
3. 写入 docs/INDEX.md（初始最小内容）

文件保护

• 已存在的文件不覆盖（AGENTS.md 除外，由用户决定）
• 创建完成后，输出需要人工填写的 [待填写] 位置列表

错误处理

• 捕获文件写入异常，显示友好错误消息
• 确保操作原子性：全部成功或全部回滚