init-agents-md Skill

Overview

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

Execute the following in the project:

/init-agents-md

Workflow

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 Template

markdown

# AGENTS.md

> 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

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
- **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 Rules (Mandatory)
- 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
- 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

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

AGENTS.md
docs/
└── INDEX.md

Initial content of
docs/INDEX.md
:

markdown

# docs/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)

| 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

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 Template (General)

markdown

# [Directory Name]/INDEX.md

> One-sentence description of the purpose of this directory.

## Current Documents

| File | Description |
|------|------|
| [filename.md](filename.md) | One-sentence description |

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

| File | Trigger Condition |
|------|---------|
| *(None yet)* | |

INDEX.md Writing Rules

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

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

File Protection

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

init-agents-md

NPX Install

Tags

SKILL.md Content (Chinese)

init-agents-md Skill

Overview

Usage

Workflow

AGENTS.md Template

Initially Generated Minimal Skeleton

Progressive Expansion Specifications

Mandatory Steps When Creating a New Subdirectory

INDEX.md Template (General)

INDEX.md Writing Rules

Implementation Details

Writing Order

File Protection

Error Handling