agents-md-gen

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Generating AGENTS.md

生成AGENTS.md

This skill explores a codebase, detects patterns and conventions, and generates a minimal AGENTS.md that gives AI coding agents just enough context to work effectively — plus progressive disclosure files for domain-specific details.

Voice: Write like someone who respects the reader's token budget AND knows what actually matters in a codebase. Benefit-first — tell the agent what it needs to succeed, not everything you know. Concrete — exact commands, exact tool names, no "use the appropriate tool." Ruthlessly concise — every line loads on every single request. If it doesn't change agent behavior, delete it.

Core principle: The ideal AGENTS.md is as small as possible. ~150-200 instructions is the effective attention budget. Every token you add displaces tokens the agent needs for the actual task.

本Skill会探索代码库，检测模式与约定，生成一个极简的AGENTS.md文件，为AI编码Agent提供足够的上下文以高效工作——同时生成用于领域特定细节的渐进式披露文件。

语气风格：以尊重读者Token预算且了解代码库核心要点的口吻撰写。优先突出价值——告诉Agent成功完成任务所需的信息，而非你知道的所有内容。内容具体——给出确切命令、确切工具名称，避免「使用合适的工具」这类表述。极度简洁——每一行内容都会在每次请求中加载。如果某行内容不会改变Agent的行为，就删掉它。

核心原则：理想的AGENTS.md文件应尽可能精简。有效注意力预算约为150-200条指令。你添加的每一个Token都会占用Agent处理实际任务所需的Token。

Phase 1: Explore the codebase

第一阶段：探索代码库

Before writing anything, understand the project deeply. The AGENTS.md will be wrong if you skip this.

在撰写任何内容之前，要深入理解项目。跳过这一步生成的AGENTS.md会存在错误。

1.1 Detect project metadata

1.1 检测项目元数据

Look for these files (check all, not just the first match):

```
package.json
```
,
```
deno.json
```
,
```
bun.lock
```
— JS/TS ecosystem
```
Cargo.toml
```
— Rust
```
go.mod
```
— Go
```
pyproject.toml
```
,
```
setup.py
```
,
```
setup.cfg
```
— Python
```
Gemfile
```
,
```
*.gemspec
```
— Ruby
```
pom.xml
```
,
```
build.gradle
```
,
```
build.gradle.kts
```
— JVM
```
*.csproj
```
,
```
*.sln
```
— .NET
```
Makefile
```
,
```
Taskfile.yml
```
,
```
justfile
```
— build entry points
```
docker-compose*.yml
```
,
```
Dockerfile
```
— containerized
IaC config files — infrastructure

Extract: project name, language(s), package manager, build system, test framework, linter, formatter.

查找以下文件（全部检查，而非仅匹配第一个）：

```
package.json
```
、
```
deno.json
```
、
```
bun.lock
```
—— JS/TS生态
```
Cargo.toml
```
—— Rust
```
go.mod
```
—— Go
```
pyproject.toml
```
、
```
setup.py
```
、
```
setup.cfg
```
—— Python
```
Gemfile
```
、
```
*.gemspec
```
—— Ruby
```
pom.xml
```
、
```
build.gradle
```
、
```
build.gradle.kts
```
—— JVM
```
*.csproj
```
、
```
*.sln
```
—— .NET
```
Makefile
```
、
```
Taskfile.yml
```
、
```
justfile
```
—— 构建入口文件
```
docker-compose*.yml
```
、
```
Dockerfile
```
—— 容器化项目
IaC配置文件 —— 基础设施类项目

提取信息：项目名称、使用语言、包管理器、构建系统、测试框架、代码检查工具、代码格式化工具。

1.2 Detect repo type

1.2 检测仓库类型

Signal	Type
`bin` field, CLI framework imports (commander, clap, cobra, click, oclif), `main` with flag parsing	CLI tool
Web framework imports (express, fastify, flask, django, gin, axum, rails), route definitions	Web app / API
`exports` / `main` with no `bin` , `lib.rs` , library-style public API, published to registry	Library
`workspaces` , `packages/` or `apps/` dirs, Nx/Turborepo/Lerna config, multiple `go.mod`	Monorepo
Helm charts, Terraform modules, Dockerfiles without app code	Infrastructure
`ios/` , `android/` , React Native/Flutter/Expo config	Mobile / native
`action.yml` , browser extension `manifest.json` , VS Code extension with `contributes`	Plugin / extension

信号	类型
包含 `bin` 字段、CLI框架导入（commander、clap、cobra、click、oclif）、带参数解析的 `main` 函数	CLI工具
Web框架导入（express、fastify、flask、django、gin、axum、rails）、路由定义	Web应用/API
有 `exports` / `main` 但无 `bin` 、 `lib.rs` 、类库风格的公共API、已发布到包仓库	类库
包含 `workspaces` 、 `packages/` 或 `apps/` 目录、Nx/Turborepo/Lerna配置、多个 `go.mod` 文件	单体仓库（Monorepo）
Helm Charts、Terraform模块、无应用代码的Dockerfile	基础设施
`ios/` 、 `android/` 目录、React Native/Flutter/Expo配置	移动/原生应用
`action.yml` 、浏览器扩展 `manifest.json` 、带 `contributes` 字段的VS Code扩展	插件/扩展

1.3 Discover local patterns and conventions

1.3 发现本地模式与约定

This is where AGENTS.md differs from a README. You're looking for things an AI agent needs to know to produce code that fits the project — not things a human user needs to get started.

Build & run commands:

How to build:
```
npm run build
```
,
```
cargo build
```
,
```
make
```
, etc.
How to run tests: exact command, including flags the project uses
How to lint/format: exact commands, including any
```
--fix
```
flags
How to typecheck: if separate from build
Any non-obvious dev setup steps

Code patterns:

Read 5-10 representative source files. Look for:
- Import style (named vs default, absolute vs relative paths, path aliases)
- Error handling patterns (Result types, try/catch style, error classes)
- Async patterns (async/await, promises, channels, goroutines)
- State management approach
- Naming conventions (camelCase, snake_case, PascalCase — for files, variables, types)
- Test file location and naming (
```
*.test.ts
```
  next to source?
```
tests/
```
  directory?
```
_test.go
```
  ?)
- Test style (describe/it, test(), #[test], table-driven)

Architecture decisions:

Don't document file paths — they go stale. Instead note the conceptual organization:
- "Feature-sliced architecture" or "MVC layout" or "domain-driven packages"
- Key domain concepts and their vocabulary (e.g., "we call them 'organizations' not 'teams'")
- Dependency direction (which layers depend on which)

Config and tooling:

```
.eslintrc
```
,
```
biome.json
```
,
```
rustfmt.toml
```
,
```
.editorconfig
```
— note their existence, don't duplicate their content
CI pipeline files — what checks must pass
Pre-commit hooks — what runs automatically

这正是AGENTS.md与README的不同之处。你需要寻找AI Agent生成符合项目风格的代码所需了解的信息——而非人类用户启动项目所需的内容。

构建与运行命令：

构建方式：
```
npm run build
```
、
```
cargo build
```
、
```
make
```
等
测试运行方式：确切命令，包括项目使用的参数
代码检查/格式化：确切命令，包括
```
--fix
```
这类参数
类型检查：如果与构建步骤分离
任何非显而易见的开发环境设置步骤

代码模式：

阅读5-10个有代表性的源文件，查找：
- 导入风格（命名导入vs默认导入、绝对路径vs相对路径、路径别名）
- 错误处理模式（Result类型、try/catch风格、错误类）
- 异步模式（async/await、Promise、通道、协程）
- 状态管理方案
- 命名约定（文件名、变量、类型使用camelCase、snake_case还是PascalCase）
- 测试文件的位置与命名（源文件旁的
```
*.test.ts
```
  ？
```
tests/
```
  目录？
```
_test.go
```
  ？）
- 测试风格（describe/it、test()、#[test]、表驱动测试）

架构决策：

不要记录文件路径——它们会过时。相反，记录概念性的组织方式：
- 「功能切片架构」或「MVC布局」或「领域驱动的包结构」
- 核心领域概念及其术语（例如：我们称它们为‘organizations’而非‘teams’）
- 依赖方向（哪些层依赖哪些层）

配置与工具：

```
.eslintrc
```
、
```
biome.json
```
、
```
rustfmt.toml
```
、
```
.editorconfig
```
——仅记录它们的存在，不要复制其内容
CI流水线文件——必须通过哪些检查
提交前钩子——自动运行的任务

1.4 Check for existing AGENTS.md / CLAUDE.md

1.4 检查现有AGENTS.md/CLAUDE.md

If one exists, read it carefully. Identify:

What's still accurate
What's stale or wrong
What's bloated (duplicates linter config, documents file paths, states the obvious)
What's genuinely useful and must be preserved

如果已存在此类文件，仔细阅读并确认：

哪些内容仍然准确
哪些内容已过时或错误
哪些内容冗余（重复代码检查工具配置、记录文件路径、陈述显而易见的内容）
哪些内容真正有用且必须保留

Phase 2: Write the files

第二阶段：编写文件

2.1 Root AGENTS.md — keep it minimal

2.1 根目录AGENTS.md——保持极简

The root file should contain ONLY what's relevant to every single task in the repo.

Required (always include):

One-sentence project description
Package manager (if not the ecosystem default)
Build / typecheck / test / lint commands (if non-standard or multi-step)

Include only if it changes agent behavior:

Key architectural constraints ("never import from
```
internal/
```
outside the package")
Domain vocabulary that differs from obvious meaning
Non-obvious conventions the linter doesn't catch
Links to progressive disclosure files

Never include:

File paths (they go stale — describe capabilities instead)
Things the linter/formatter already enforces (the agent will see the errors)
Obvious coding practices ("write clean code", "use meaningful names")
Full language style guides (move to separate files)
Comprehensive architecture overviews (move to separate file)

Template for a single repo:

markdown

undefined

根目录文件应仅包含与仓库中所有任务相关的内容。

必填内容（始终包含）：

一句话项目描述
包管理器（如果不是生态系统默认的）
构建/类型检查/测试/代码检查命令（如果非标准或多步骤）

仅当会改变Agent行为时才包含：

核心架构约束（「永远不要从
```
internal/
```
包外导入内容」）
与常规含义不同的领域术语
工具未强制执行的非显而易见约定
指向渐进式披露文件的链接

永远不要包含：

文件路径（会过时——改为描述功能）
代码检查/格式化工具已强制执行的内容（Agent会看到错误提示）
显而易见的编码实践（「编写整洁代码」、「使用有意义的命名」）
完整的语言风格指南（移至单独文件）
全面的架构概述（移至单独文件）

单仓库模板：

markdown

undefined

AGENTS.md

[One sentence: what this project is.]

[一句话：本项目是什么。]

Commands

命令

[Only non-obvious ones. Skip if standard.]

Build:
```
[command]
```
Test:
```
[command]
```
Test single:
```
[command for running one test]
```
Lint:
```
[command]
```
Typecheck:
```
[command]
```
Format:
```
[command]
```

[仅包含非标准命令。标准命令可省略。]

构建：
```
[命令]
```
测试：
```
[命令]
```
单测运行：
```
[运行单个测试的命令]
```
代码检查：
```
[命令]
```
类型检查：
```
[命令]
```
格式化：
```
[命令]
```

Conventions

约定

[3-7 bullets max. Only things the agent would get wrong without being told.]

[Convention that isn't enforced by tooling]
[Domain term clarification]
[Architectural constraint]

For [language] conventions, see

docs/[LANGUAGE].md

. For testing patterns, see

docs/TESTING.md


Template for a monorepo:

```markdown

[最多3-7条。仅包含Agent被告知前会出错的内容。]

[工具未强制执行的约定]
[领域术语说明]
[架构约束]

关于[语言]约定，请查看

docs/[LANGUAGE].md

。关于测试模式，请查看

docs/TESTING.md

。


单体仓库模板：

```markdown

AGENTS.md

[One sentence: what this monorepo contains.]

Uses [package manager] workspaces.

[一句话：本单体仓库包含什么。]

使用[包管理器]工作区。

Commands

命令

Install:
```
[command]
```
Build all:
```
[command]
```
Test all:
```
[command]
```

安装：
```
[命令]
```
全量构建：
```
[命令]
```
全量测试：
```
[命令]
```

Structure

结构

[Brief conceptual description — not file paths.]

See each package's AGENTS.md for package-specific conventions.

undefined

[简短的概念性描述——不要写文件路径。]

请查看每个包的AGENTS.md以了解包特定约定。

undefined

2.2 Progressive disclosure files

2.2 渐进式披露文件

Create separate files for domain-specific guidance. Only create files for areas where the project has meaningful conventions that aren't enforced by tooling.

When to create a separate file:

5+ related conventions that only matter for one domain
Language-specific patterns the project follows consistently
Testing patterns that differ from framework defaults
API design patterns specific to the project

When NOT to create a separate file:

The conventions are already in linter/formatter config
There are fewer than 3 conventions to document
The information is available in framework docs the agent already knows

Format for progressive disclosure files:

markdown

undefined

为领域特定指导创建单独文件。仅当项目存在工具未强制执行的有意义约定时才创建文件。

何时创建单独文件：

5个以上相关约定，且仅与某一领域相关
项目一致遵循的语言特定模式
与框架默认不同的测试模式
项目特有的API设计模式

何时不创建单独文件：

约定已在代码检查/格式化配置中定义
要记录的约定少于3条
信息已在Agent已知的框架文档中

渐进式披露文件格式：

markdown

undefined

[Domain] Conventions

[领域]约定

[2-3 sentences of context: what this covers and why.]

[2-3句话的上下文：涵盖内容及原因。]

[Category]

[分类]

[Convention with brief rationale]
[Convention with brief rationale]

[约定及简要理由]
[约定及简要理由]

[Category]

[分类]

[Convention with brief rationale]


Keep each file under 100 lines. If it's longer, split it further.

[约定及简要理由]


每个文件保持在100行以内。如果过长，进一步拆分。

2.3 Monorepo: package-level AGENTS.md

2.3 单体仓库：包级AGENTS.md

For monorepos, each package/app with its own conventions gets its own AGENTS.md:

markdown

undefined

对于单体仓库，每个有独立约定的包/应用都应有自己的AGENTS.md：

markdown

undefined

AGENTS.md

[One sentence: what this package does.]

[Stack: e.g., "TypeScript + Express + Prisma"]

[一句话：本包的功能。]

[技术栈：例如，"TypeScript + Express + Prisma"]

Commands

命令

Test:
```
[package-specific command]
```
Dev:
```
[package-specific command]
```

测试：
```
[包特定命令]
```
开发：
```
[包特定命令]
```

Conventions

约定

[Package-specific convention]


Don't repeat root-level conventions. The agent sees both files merged.

[包特定约定]


不要重复根目录级别的约定。Agent会合并读取两个文件的内容。

2.4 Infuse stack best practices

2.4 融入技术栈最佳实践

Based on the detected stack, include conventions that experienced engineers follow but agents commonly get wrong. Only include what's relevant to the actual project.

These should go in progressive disclosure files, not the root AGENTS.md.

Examples of high-value, stack-specific guidance:

"Use
```
Result<T, E>
```
for recoverable errors,
```
panic!
```
only for invariant violations" (Rust)
"Prefer server components by default. Add
```
'use client'
```
only when hooks or browser APIs are needed" (Next.js App Router)
"Use
```
errgroup
```
for concurrent operations that should fail together" (Go)
"Test behavior, not implementation. Mock at the boundary, not the unit" (any)
"Prefer
```
Depends()
```
injection over importing services directly" (FastAPI)

Don't dump a style guide. Pick the 5-10 things the agent is most likely to get wrong based on what you saw in the actual code.

根据检测到的技术栈，加入经验丰富的工程师遵循但Agent常出错的约定。仅包含与实际项目相关的内容。

这些内容应放在渐进式披露文件中，而非根目录AGENTS.md。

高价值、技术栈特定指导示例：

"可恢复错误使用
```
Result<T, E>
```
，仅在违反不变式时使用
```
panic!
```
"（Rust）
"默认优先使用服务端组件。仅在需要钩子或浏览器API时添加
```
'use client'
```
"（Next.js App Router）
"使用
```
errgroup
```
处理需同时失败的并发操作"（Go）
"测试行为而非实现。在边界处Mock，而非单元内部"（通用）
"优先使用
```
Depends()
```
注入而非直接导入服务"（FastAPI）

不要直接照搬风格指南。根据你在实际代码中看到的内容，挑选Agent最可能出错的5-10个点。

Phase 3: Verify

第三阶段：验证

Before presenting the output:

Token budget check. Is the root AGENTS.md under 50 lines? If not, move content to progressive disclosure files.
Every command must be real. Verify build/test/lint commands exist in package.json, Makefile, or equivalent.
No file paths in root AGENTS.md. Describe capabilities, not locations. Paths to progressive disclosure docs are the only exception.
No duplication with tooling. If the linter enforces it, don't document it.
No obvious advice. Read every line and ask: "Would the agent do the wrong thing without this?" If not, delete it.
No stale content. If preserving parts of an existing AGENTS.md, verify those parts are still accurate.
Progressive disclosure files are referenced. Every file you create must be linked from the root or from a parent file.
Read it as the agent. On every request, this loads before the user's task. Is every line worth that cost?

在提交输出前：

Token预算检查：根目录AGENTS.md是否少于50行？如果不是，将内容移至渐进式披露文件。
命令真实性验证：确保所有包含的命令在package.json、Makefile或等效文件中存在。
根目录无文件路径：描述功能而非位置。渐进式披露文档的路径是唯一例外。
不与工具配置重复：如果代码检查工具已强制执行，无需记录。
无显而易见的建议：逐行阅读并问自己："如果没有这条，Agent会做错吗？"如果不会，删掉它。
无过时内容：如果保留现有AGENTS.md的部分内容，验证这些内容是否仍然准确。
渐进式披露文件已关联：你创建的每个文件都必须从根目录或父文件链接。
从Agent视角阅读：每次请求时，这些内容会在用户任务前加载。每一行都值得这个成本吗？

Decision Policy

决策规则

ALWAYS explore the codebase before writing. Never generate from the project name alone.
ALWAYS read actual source files to discover patterns. Don't infer conventions from metadata alone.
ALWAYS verify every command you include by checking package.json / Makefile / build configs.
ALWAYS prefer smaller. When in doubt, leave it out. The agent can discover things at runtime.
Ask before replacing: if an AGENTS.md already exists, show the user what you'd change and confirm. Existing files may contain hard-won knowledge.
Describe capabilities, not file paths: "Authentication is handled via JWT middleware" not "Auth lives in src/middleware/auth.ts."
Don't duplicate linter config: if
```
.eslintrc
```
says no
```
var
```
, you don't need to say it again.
Don't state the obvious: "Use TypeScript" in a TypeScript project wastes tokens.
Monorepos get layered files: root + per-package. Don't repeat root conventions in packages.
Stack best practices go in separate files: keep the root clean.

始终先探索代码库再撰写内容。绝不仅根据项目名称生成。
始终阅读实际源文件以发现模式。绝不仅从元数据推断约定。
始终通过检查package.json/Makefile/构建配置验证你包含的每个命令。
始终优先精简。存疑时，就删掉。Agent可以在运行时发现信息。
替换前询问：如果已存在AGENTS.md，向用户展示你要修改的内容并确认。现有文件可能包含来之不易的经验。
描述功能而非文件路径："认证通过JWT中间件处理"而非"认证代码在src/middleware/auth.ts"。
不重复代码检查工具配置：如果
```
.eslintrc
```
禁止使用
```
var
```
，无需再次说明。
不陈述显而易见的内容：在TypeScript项目中说"使用TypeScript"会浪费Token。
单体仓库使用分层文件：根目录+每个包的文件。不要在包中重复根目录约定。
技术栈最佳实践放在单独文件：保持根目录简洁。

Safety Rules

安全规则

No secrets in output: if you find API keys, tokens, or credentials while exploring, do not include them. Use placeholder names.
No invented conventions: only document patterns you actually observed in the code. If you're unsure, read more files to confirm.
Read-only exploration: do not modify any project files during the explore phase. Only write AGENTS.md and progressive disclosure files.
Preserve institutional knowledge: if an existing AGENTS.md has non-obvious rules (e.g., "never use ORM for the analytics database — it's a different engine"), keep them even if you don't fully understand why.

输出中无敏感信息：如果在探索时发现API密钥、Token或凭证，不要包含在输出中。使用占位符名称。
不编造约定：仅记录你在代码中实际观察到的模式。如果不确定，阅读更多文件确认。
仅读取探索：在探索阶段不要修改任何项目文件。仅编写AGENTS.md和渐进式披露文件。
保留机构知识：如果现有AGENTS.md包含非显而易见的规则（例如，"永远不要为分析数据库使用ORM——它是不同的引擎"），即使你不完全理解原因，也要保留它们。

Error Handling

错误处理

Empty repo / no code: tell the user there's nothing to document yet. A project description placeholder is all you can offer.
No package manifest: determine stack from code structure, imports, and file extensions instead.
Existing AGENTS.md with custom content: don't silently overwrite. Show what you'd change and get confirmation.
Can't determine conventions: when the codebase is inconsistent (mixed styles, no clear patterns), note the inconsistency to the user and ask what they want to standardize.
Massive monorepo: focus on root AGENTS.md + the 3-5 most active packages. Don't try to cover everything in one pass.
Conflicting patterns: if different parts of the codebase follow different conventions, flag the contradiction. Ask the user which to standardize on.

空仓库/无代码：告知用户目前没有可记录的内容。只能提供项目描述占位符。
无包清单：从代码结构、导入和文件扩展名推断技术栈。
现有AGENTS.md包含自定义内容：不要静默覆盖。向用户展示你要修改的内容并获取确认。
无法确定约定：当代码库不一致（混合风格、无清晰模式）时，向用户说明这种不一致并询问要标准化的内容。
大型单体仓库：重点关注根目录AGENTS.md+3-5个最活跃的包。不要试图一次覆盖所有内容。
模式冲突：如果代码库不同部分遵循不同约定，标记这种矛盾并询问用户要标准化哪一种。",