init-agents-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

init-agents-md Skill

概述

Overview

此 skill 用于在项目根目录生成

AGENTS.md

入口文件和

docs/

最小骨架，建立面向 agent 的文档治理体系。

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

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

This skill is used to generate the

AGENTS.md

entry file and the minimal skeleton of

docs/

in the project root directory, establishing a document governance system for agent-oriented projects.

The core design principles are derived from OpenAI Harness Engineering practices:

AGENTS.md is a directory, not an encyclopedia: An ~100-line entry pointing to deeper truths in docs/
The repository is a systematic record of knowledge: What an Agent cannot see is equivalent to non-existence for it
Progressive disclosure: Start with the minimal skeleton, and documents are created on demand as project complexity increases
INDEX.md is the navigation layer: Each directory must have an
```
INDEX.md
```
, and Agents retrieve documents by reading indexes layer by layer instead of scanning the directory tree

使用方式

Usage

在项目中执行：

/init-agents-md

Execute the following in the project:

/init-agents-md

工作流程

Workflow

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

Check if
```
AGENTS.md
```
already exists in the project root directory
If it exists → Prompt the user to choose to overwrite or skip
If it does not exist → Write the
```
AGENTS.md
```
template + create the minimal
```
docs/
```
skeleton
Display a success message and prompt the user to fill in the
```
[To be filled]
```
placeholder content

AGENTS.md 模板

AGENTS.md Template

markdown

undefined

markdown

undefined

AGENTS.md

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

This file is the entry map for AI working in this repository, keep it concise (<100 lines). Principle: A directory, not an encyclopedia. What an Agent cannot see is equivalent to non-existence for it.

文档检索方式

Document Retrieval Method

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

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

从

docs/INDEX.md

开始检索。

All documents are navigated through INDEX.md layer by layer; directory tree scanning is prohibited:

AGENTS.md
  └─ docs/INDEX.md
       ├─ docs/design-docs/INDEX.md → Specific design documents
       └─ docs/usage/INDEX.md       → Usage guides

Start retrieval from

docs/INDEX.md

仓库结构

Repository Structure

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

[Project maintainers describe key directories and modules here]

编码规范与黄金原则

Coding Standards and Golden Principles

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

[Project maintainers add technology stack-related standards here]

文档治理

Document Governance

人工审批规则

Manual Approval Rules

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

No autonomous creation: AI shall not create any documents or directories on its own; it must first request manual approval
No autonomous modification: AI must explain the modification content and reasons before modifying documents, and obtain manual consent

INDEX.md 规则（强制）

INDEX.md Rules (Mandatory)

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

Each subdirectory under
```
docs/
```
must have an
```
INDEX.md
```
```
INDEX.md
```
only serves as navigation: file name + one-sentence description, no actual content is allowed
When creating a new subdirectory, the
```
INDEX.md
```
for that directory must be created synchronously, and the parent
```
INDEX.md
```
must be updated
Directories without
```
INDEX.md
```
are equivalent to non-existence for Agents

渐进式文档策略

Progressive Document Strategy

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

---

In the early stage of the project, only maintain
```
AGENTS.md
```
and
```
docs/INDEX.md
```
When new documents are needed: AI submits a request → Manual approval → AI creates the document + updates the corresponding INDEX.md
Empty indexes are normal; documents should only be created when truly needed

---

初始生成的最小骨架

Initially Generated Minimal Skeleton

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

AGENTS.md
docs/
└── INDEX.md

docs/INDEX.md
初始内容：

markdown

undefined

When executing this skill, only the following minimal structure is generated:

AGENTS.md
docs/
└── INDEX.md

Initial content of
docs/INDEX.md
:

markdown

undefined

docs/INDEX.md

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

This directory is the project knowledge base. Navigate through this file; directory tree scanning is prohibited. Each subdirectory has an independent INDEX.md, which can be accessed progressively on demand.

当前文档

Current Documents

路径	描述
(暂无子目录)

Path	Description
(No subdirectories yet)

待创建文档（按需触发）

To-be-created Documents (On-demand Trigger)

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

---

Directory/File	Trigger Condition
`design-docs/`	When formal design decisions need to be recorded
`usage/`	When usage specifications need to be explained to users or Agents
`ARCHITECTURE.md`	When the project has more than 3 clear module boundaries
`DESIGN.md`	When core beliefs and design principles need to be solidified
`QUALITY.md`	When CI is introduced to the project and quality scores need to be tracked

---

渐进式扩展规范

Progressive Expansion Specifications

新建子目录时的强制步骤

Mandatory Steps When Creating a New Subdirectory

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

Create
```
INDEX.md
```
in the target path (using the template below)
Add a new row to the "Current Documents" table in the parent
```
INDEX.md
```
Remove the directory from the "To-be-created" table in the parent (if it exists)

INDEX.md 模板（通用）

INDEX.md Template (General)

markdown

undefined

markdown

undefined

[目录名]/INDEX.md

[Directory Name]/INDEX.md

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

One-sentence description of the purpose of this directory.

当前文档

Current Documents

文件	描述
文件名.md	一句话描述

File	Description
filename.md	One-sentence description

待创建文档（按需触发）

To-be-created Documents (On-demand Trigger)

文件	触发条件
(暂无)

undefined

File	Trigger Condition
(None yet)

undefined

INDEX.md 写作规则

INDEX.md Writing Rules

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

Only for navigation: File name + one-sentence description, no actual content allowed
Keep concise: Each description shall not exceed 20 characters
Update promptly: INDEX.md must be updated synchronously when adding/deleting documents
Trigger conditions: To-be-created documents must specify trigger conditions, no empty placeholders allowed

实现细节

Implementation Details

写入顺序

Writing Order

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

Write
```
AGENTS.md
```
Create the
```
docs/
```
directory
Write the initial minimal content of
```
docs/INDEX.md
```

文件保护

File Protection

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

Existing files will not be overwritten (except
```
AGENTS.md
```
, which is decided by the user)
After creation, output a list of
```
[To be filled]
```
positions that require manual filling

错误处理

Error Handling

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

Capture file writing exceptions and display user-friendly error messages
Ensure atomicity of operations: All succeed or all roll back