agents-md-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AGENTS.md Generator (Root + Nested, Portable)

AGENTS.md生成器（根目录与嵌套目录，可移植）

Goal

目标

Maintain small, high-signal AGENTS.md files:

Root AGENTS.md — purpose of repository, navigation, universal toolchain, canonical commands, links to docs and skills.
Nested AGENTS.md — module/package purpose, local commands, module references.

Use progressive disclosure: keep AGENTS.md concise; push details to docs or skills.

维护精简、高信息密度的AGENTS.md文件：

根目录AGENTS.md —— 说明仓库用途、导航指引、通用工具链、标准命令、文档及技能链接。
嵌套目录AGENTS.md —— 说明模块/包用途、本地命令、模块参考信息。

使用渐进式披露：保持AGENTS.md简洁，将详细内容转移至文档或技能中。

Skill location (agent-specific)

技能位置（Agent专属）

Do NOT assume
.agents/
or any fixed directory exists.
Skills may live:
- inside the repository (embedded),
- or in an external/global skill library (external).
If referencing local skills, first detect an existing skill root already used by the project.
If no local skill directory exists — reference skills by name only (external).
Never create hidden agent directories just to store skills.

请勿假设
.agents/
或任何固定目录已存在。
技能可存放于：
- 仓库内部（嵌入式），
- 或外部/全局技能库（外部）。
若引用本地技能，需先检测项目已在使用的现有技能根目录。
若不存在本地技能目录 —— 仅通过名称引用技能（外部）。
切勿为存储技能而创建隐藏的Agent目录。

When to run

运行时机

Run this skill when:

AGENTS.md is missing, bloated, contradictory, or outdated.
A new package/service/module appears.
Repository structure changes (monorepo growth or split).
Teams want consistent agent context across diverse stacks.

在以下场景运行此技能：

AGENTS.md缺失、冗余、矛盾或过时。
出现新的包/服务/模块。
仓库结构变更（单体仓库扩容或拆分）。
团队希望在不同技术栈中保持一致的Agent上下文。

Workflow (Deterministic)

工作流程（确定性）

1. Discover repository shape

1. 发现仓库结构

Identify repository root (git root if available).

Detect language/tool markers:

```
package.json
```
,
```
pnpm-workspace.yaml
```
```
go.mod
```
,
```
go.work
```
```
pyproject.toml
```
```
Cargo.toml
```
```
pubspec.yaml
```
```
pom.xml
```
,
```
build.gradle
```

Locate
```
docs/
```
,
```
README.md
```
, existing
```
AGENTS.md
```
.

识别仓库根目录（若可用则采用git根目录）。

检测语言/工具标识：

```
package.json
```
、
```
pnpm-workspace.yaml
```
```
go.mod
```
、
```
go.work
```
```
pyproject.toml
```
```
Cargo.toml
```
```
pubspec.yaml
```
```
pom.xml
```
、
```
build.gradle
```

定位
```
docs/
```
、
```
README.md
```
、已存在的
```
AGENTS.md
```
。

2. Detect module boundaries

2. 检测模块边界

Create nested AGENTS.md if directory:

Contains independent build/package manifest
OR represents deployable/service unit (
```
apps/
```
,
```
services/
```
,
```
packages/
```
)
AND differs in stack/toolchain from parent scope

当目录满足以下条件时，创建嵌套AGENTS.md：

包含独立的构建/包清单
或代表可部署/服务单元（如
```
apps/
```
、
```
services/
```
、
```
packages/
```
）
且与父级范围的技术栈/工具链不同

3. Generate/Update Root AGENTS.md

3. 生成/更新根目录AGENTS.md

Constraints:

Ideal size: ≤ 60 lines
Must include:
- One-sentence repository purpose
- Primary toolchain/package manager
- Canonical commands (if non-standard)
- Links to docs
- Instruction to read nested AGENTS.md when inside modules
- Optional skill references (adaptive: local or external)

约束条件：

理想篇幅：≤ 60行
必须包含：
- 一句话描述仓库用途
- 主要工具链/包管理器
- 标准命令（若为非通用标准）
- 文档链接
- 在模块内时阅读嵌套AGENTS.md的指引
- 可选技能引用（自适应：本地或外部）

4. Generate/Update Nested AGENTS.md

4. 生成/更新嵌套AGENTS.md

Constraints:

Ideal size: ≤ 40 lines
Must include:
- One-sentence module purpose
- Module-specific commands
- Local documentation references
- Optional skill references (adaptive)

约束条件：

理想篇幅：≤ 40行
必须包含：
- 一句话描述模块用途
- 模块专属命令
- 本地文档引用
- 可选技能引用（自适应）

5. Progressive Disclosure Rules

5. 渐进式披露规则

Do not embed style guides, CI policies, or architecture details.
Prefer links to:
- ```
docs/STYLE_GUIDE.md
```
- ```
docs/ARCHITECTURE.md
```
- external or local skills
Avoid “always/never” rules unless critical for correctness/security.

请勿嵌入风格指南、CI策略或架构细节。
优先链接至：
- ```
docs/STYLE_GUIDE.md
```
- ```
docs/ARCHITECTURE.md
```
- 外部或本地技能
除非对正确性/安全性至关重要，否则避免使用“始终/绝不”类规则。

6. Safety / Correctness Gates

6. 安全/正确性校验

Never invent commands.
Infer commands from:
- package scripts
- Makefile
- CI configuration
- README
If uncertain → write: “Known commands: see <file>”
Preserve critical warnings (security, secrets, deployment).

切勿凭空生成命令。
从以下来源推导命令：
- 包脚本
- Makefile
- CI配置
- README
若存在不确定性 → 编写： “已知命令：请查看<文件>”
保留关键警告（安全、密钥、部署相关）。

Output Contract

输出约定

Create or update only:

```
<repo_root>/AGENTS.md
```
```
<module_dir>/AGENTS.md
```

Do not create agent configuration folders.

仅创建或更新：

```
<repo_root>/AGENTS.md
```
```
<module_dir>/AGENTS.md
```

请勿创建Agent配置文件夹。

Skill Referencing Strategy

技能引用策略

When adding skill references inside AGENTS.md:

If local skill directory detected

See: <detected-skill-root>/<skill-name>/SKILL.md

If no local directory exists
```
Skill: agents-md-generator (external)
```

Never assume filesystem paths.

在AGENTS.md中添加技能引用时：

若检测到本地技能目录

See: <detected-skill-root>/<skill-name>/SKILL.md

若不存在本地目录
```
Skill: agents-md-generator (external)
```

切勿假设文件系统路径。