agents-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

This skill provides expert guidance for creating, verifying, and improving AGENTS.md files - the open standard format for guiding AI coding agents.

本技能为AGENTS.md文件的创建、验证和改进提供专业指导——AGENTS.md是用于指导AI编码Agent的开放标准格式。

What is AGENTS.md?

什么是AGENTS.md？

AGENTS.md is a simple, open format for guiding coding agents, used by over 60k open-source projects. Think of it as a README for agents: a dedicated, predictable place to provide context and instructions to help AI coding agents work on your project.

Key principle: Unlike README.md (which is for humans), AGENTS.md contains the extra, detailed context coding agents need: build steps, tests, conventions, and instructions that might clutter a README.

Learn more: https://agents.md/ | https://www.aihero.dev/a-complete-guide-to-agents-md

AGENTS.md是一种简单的开放格式，用于指导编码Agent，已被超过6万个开源项目采用。你可以把它看作是Agent专属的README：一个专门的、可预测的位置，用于为AI编码Agent提供上下文和指令，帮助它们在你的项目中工作。

核心原则： 与面向人类的README.md不同，AGENTS.md包含编码Agent所需的额外详细上下文：构建步骤、测试、约定以及可能会让README显得杂乱的指令。

Quick Start

快速开始

When users want to create an AGENTS.md file

当用户想要创建AGENTS.md文件时

Start by asking these clarifying questions:

Project type: Monorepo or single package?
Tech stack: What languages/frameworks?
Package manager: npm, pnpm, yarn, bun, or something else?
Build/test commands: Any non-standard commands?
Specific concerns: Any patterns you want to encourage or avoid?

Then create a minimal AGENTS.md following the template below.

首先提出以下澄清问题：

项目类型： 单体仓库（Monorepo）还是单个包？
技术栈： 使用什么语言/框架？
包管理器： npm、pnpm、yarn、bun还是其他？
构建/测试命令： 是否有非标准命令？
特定注意事项： 有没有想要鼓励或避免的模式？

然后按照以下模板创建一个简洁的AGENTS.md文件。

When users want to verify an existing AGENTS.md

当用户想要验证现有AGENTS.md文件时

Run through the verification checklist (see Verification below).

按照验证清单进行检查（见下方【验证】部分）。

When users want to improve an existing AGENTS.md

当用户想要改进现有AGENTS.md文件时

Assess the file and suggest progressive disclosure refactoring (see Improvement below).

评估文件并建议采用渐进式披露原则进行重构（见下方【改进】部分）。

Core Principles

核心原则

1. Minimal Root AGENTS.md

1. 简洁的根目录AGENTS.md

The root AGENTS.md should be as small as possible. Every token gets loaded on every request, so keep only what's relevant to every single task.

Essential elements only:

One-sentence project description (acts as a role-based prompt)
Package manager (if not npm; or use corepack for warnings)
Non-standard build/typecheck commands
Links to progressive disclosure files

根目录的AGENTS.md应尽可能简洁。每个令牌都会在每次请求时加载，因此只保留与所有任务相关的内容。

仅保留必要元素：

一句话项目描述（作为基于角色的提示）
包管理器（如果不是npm；或使用corepack给出警告）
非标准构建/类型检查命令
指向渐进式披露文件的链接

2. Progressive Disclosure

2. 渐进式披露

Instead of cramming everything into AGENTS.md, give the agent only what it needs right now, and point to other resources when needed.

Example - Don't do this:

markdown

undefined

不要将所有内容都塞进AGENTS.md，只给Agent当前需要的信息，在需要时再指向其他资源。

反例：

markdown

undefined

Code style

代码风格

Always use const instead of let
Use interface instead of type when possible
Prefer functional patterns
No semicolons
Single quotes only
... (50 more lines)


**Do this instead:**
```markdown
For TypeScript conventions, see docs/TYPESCRIPT.md

Benefits:

TypeScript rules only load when the agent writes TypeScript
Other tasks don't waste tokens
File stays focused and portable across model changes

始终使用const而非let
尽可能使用interface而非type
优先使用函数式模式
不使用分号
仅使用单引号
...（还有50多行）


**正确做法：**
```markdown
关于TypeScript约定，请查看docs/TYPESCRIPT.md

优势：

TypeScript规则仅在Agent编写TypeScript代码时才会加载
其他任务不会浪费令牌
文件保持聚焦，且在模型变更时仍具可移植性

3. Describe Capabilities, Not File Structure

3. 描述能力，而非文件结构

File paths change constantly. Documenting structure leads to stale information that actively poisons context.

Don't:

markdown

Authentication logic lives in src/auth/handlers.ts

Do:

markdown

Authentication uses JWT tokens with refresh token rotation.
Look for modules matching **/auth/**/*.ts for implementation.

文件路径经常变化。记录结构会导致信息过时，反而会干扰上下文。

错误做法：

markdown

认证逻辑位于src/auth/handlers.ts

正确做法：

markdown

认证使用带刷新令牌轮换的JWT令牌。
查找匹配**/auth/**/*.ts的模块以查看实现细节。

4. Nested AGENTS.md for Monorepos

4. 单体仓库的嵌套AGENTS.md

Place AGENTS.md files in subdirectories - they merge with the root level.

Level	Content
Root	Monorepo purpose, navigation, shared tools
Package	Package purpose, tech stack, specific conventions

Root AGENTS.md:

markdown

This is a monorepo containing web services and CLI tools.

Use pnpm workspaces to manage dependencies.

See each package's AGENTS.md for specific guidelines.

Package AGENTS.md (packages/api/AGENTS.md):

markdown

This package is a Node.js GraphQL API using Prisma.

Follow docs/API_CONVENTIONS.md for API design patterns.

在子目录中放置AGENTS.md文件——它们会与根目录的文件合并。

层级	内容
根目录	单体仓库用途、导航方式、共享工具
包	包的用途、技术栈、特定约定

根目录AGENTS.md示例：

markdown

这是一个包含Web服务和CLI工具的单体仓库。

使用pnpm workspaces管理依赖。

请查看每个包的AGENTS.md获取具体指南。

包级AGENTS.md示例（packages/api/AGENTS.md）：

markdown

本包是一个使用Prisma的Node.js GraphQL API。

请遵循docs/API_CONVENTIONS.md中的API设计模式。

Templates

模板

Minimal Single-Package AGENTS.md

简洁的单包AGENTS.md

markdown

undefined

markdown

undefined

AGENTS.md

[One-sentence description of what this project is]

[一句话描述本项目的用途]

Package Manager

包管理器

This project uses [pnpm/yarn/bun]. [Optional: brief note if workspaces/monorepo]

本项目使用[pnpm/yarn/bun]。（可选：如果是单体仓库/workspace，可添加简短说明）

Build & Test

构建与测试

Build:
```
command here
```
Test:
```
command here
```
Typecheck:
```
command here
```
(if non-standard)

构建：
```
此处填写命令
```
测试：
```
此处填写命令
```
类型检查：
```
此处填写命令
```
（如果是非标准命令）

Progressive Disclosure

渐进式披露

undefined

undefined

Minimal Monorepo Root AGENTS.md

简洁的单体仓库根目录AGENTS.md

markdown

undefined

markdown

undefined

AGENTS.md

This is a monorepo containing [brief description of packages].

这是一个包含[包的简短描述]的单体仓库。

Package Manager

包管理器

Use [pnpm workspaces/yarn workspaces] to manage dependencies.

使用[pnpm workspaces/yarn workspaces]管理依赖。

Navigation

导航方式

Use
```
pnpm --filter <package_name>
```
to run commands in specific packages
Each package has its own AGENTS.md with specific guidelines

使用
```
pnpm --filter <package_name>
```
在特定包中运行命令
每个包都有自己的AGENTS.md，包含具体指南

Packages

包列表

```
package-name
```
: [brief purpose]
```
package-name
```
: [brief purpose]

undefined

```
package-name
```
: [简要用途]
```
package-name
```
: [简要用途]

undefined

Package-Level AGENTS.md (Monorepo)

单体仓库的包级AGENTS.md

markdown

undefined

markdown

undefined

AGENTS.md

[One-sentence description of this package]

[一句话描述本包的用途]

Tech Stack

技术栈

[Framework]
[Language]
[Key libraries]

[框架]
[语言]
[核心库]

Commands

命令

Build:
```
command here
```
Test:
```
command here
```
Dev:
```
command here
```

构建：
```
此处填写命令
```
测试：
```
此处填写命令
```
开发：
```
此处填写命令
```

Progressive Disclosure

渐进式披露

undefined

undefined

Verification

验证

When verifying an existing AGENTS.md, check for these issues:

验证现有AGENTS.md文件时，检查以下问题：

Bloat Indicators

冗余指标

Contradiction Detection

矛盾检测

Look for conflicting instructions:

"Use functional patterns" vs "Use classes for X"
"Prefer composition" vs "Use inheritance for Y"
"Always use X" vs "In cases of Y, use Z"

查找相互冲突的指令：

“使用函数式模式” vs “为X使用类”
“优先使用组合” vs “为Y使用继承”
“始终使用X” vs “在Y情况下使用Z”

Stale Information Risks

过时信息风险

Specific file paths (especially src/ directories)
Lists of files or modules
Version-specific toolchain commands
Outdated architecture descriptions

具体文件路径（尤其是src/目录下的）
文件或模块列表
特定版本的工具链命令
过时的架构描述

Best Practices Compliance

最佳实践合规性

Improvement

改进

Refactoring Bloated AGENTS.md

重构冗余的AGENTS.md

Use this process to refactor a bloated AGENTS.md:

Find contradictions: Identify conflicting instructions and ask which to keep
Extract essentials: Keep only what belongs in root AGENTS.md
Group the rest: Organize remaining instructions into logical categories
Create file structure: Set up progressive disclosure hierarchy
Flag for deletion: Remove redundant, vague, or obvious instructions

Prompt template to use:

text

I want you to refactor my AGENTS.md file to follow progressive disclosure principles.

1. **Find contradictions**: Identify any instructions that conflict with each other.
   For each contradiction, ask me which version I want to keep.

2. **Identify the essentials**: Extract only what belongs in the root AGENTS.md:
   - One-sentence project description
   - Package manager (if not npm)
   - Non-standard build/typecheck commands
   - Anything truly relevant to every single task

3. **Group the rest**: Organize remaining instructions into logical categories
   (e.g., TypeScript conventions, testing patterns, API design, Git workflow).

4. **Create the file structure**: Output:
   - A minimal root AGENTS.md with markdown links to the separate files
   - Each separate file with its relevant instructions
   - A suggested docs/ folder structure

5. **Flag for deletion**: Identify any instructions that are:
   - Redundant (the agent already knows this)
   - Too vague to be actionable
   - Overly obvious (like "write clean code")

按照以下流程重构冗余的AGENTS.md：

查找矛盾：识别相互冲突的指令，并询问用户保留哪一个
提取必要内容：只保留属于根目录AGENTS.md的内容
分组其余内容：将剩余指令按逻辑类别整理
创建文件结构：建立渐进式披露层级
标记待删除内容：移除冗余、模糊或显而易见的指令

可使用的提示模板：

text

我希望你遵循渐进式披露原则重构我的AGENTS.md文件。

1. **查找矛盾**：识别任何相互冲突的指令。
   对于每个矛盾，询问我想要保留哪一个版本。

2. **识别必要内容**：仅提取属于根目录AGENTS.md的内容：
   - 一句话项目描述
   - 包管理器（如果不是npm）
   - 非标准构建/类型检查命令
   - 与所有任务真正相关的内容

3. **分组其余内容**：将剩余指令按逻辑类别整理
   （例如TypeScript约定、测试模式、API设计、Git工作流）。

4. **创建文件结构**：输出：
   - 一个简洁的根目录AGENTS.md，包含指向单独文件的Markdown链接
   - 每个单独文件包含相关指令
   - 建议的docs/文件夹结构

5. **标记待删除内容**：识别以下类型的指令：
   - 冗余的（Agent已经知道的内容）
   - 过于模糊无法执行的
   - 过于显而易见的（比如“编写干净的代码”）

Creating Progressive Disclosure Files

创建渐进式披露文件

Suggested structure:

docs/
├── TYPESCRIPT.md       # TypeScript patterns and conventions
├── TESTING.md          # Testing strategies and frameworks
├── API_CONVENTIONS.md  # API design patterns (if applicable)
├── ARCHITECTURE.md     # High-level architecture (capabilities, not file paths)
└── Git worklow items → CONTRIBUTING.md

Each file should:

Be focused on one domain
Link to related files for navigation
Describe principles, not prescriptions
Include examples where helpful

建议的结构：

docs/
├── TYPESCRIPT.md       # TypeScript模式与约定
├── TESTING.md          # 测试策略与框架
├── API_CONVENTIONS.md  # API设计模式（如适用）
├── ARCHITECTURE.md     # 高层级架构（描述能力，而非文件路径）
└── Git工作流内容 → CONTRIBUTING.md

每个文件应：

聚焦一个领域
链接到相关文件以便导航
描述原则，而非硬性规定
必要时包含示例

Common Issues & Solutions

常见问题与解决方案

Issue	Solution
Agent uses wrong package manager	Explicitly specify: "This project uses pnpm"
Agent generates wrong commands	List non-standard build/test commands
File gets too large	Apply progressive disclosure - move domain rules to separate files
Instructions conflict	Review for contradictions and resolve
Agent looks in wrong places	Describe capabilities, not file paths
Mixed conventions over time	Treat AGENTS.md as living documentation, review periodically

问题	解决方案
Agent使用了错误的包管理器	明确指定：“本项目使用pnpm”
Agent生成了错误的命令	列出非标准的构建/测试命令
文件过大	应用渐进式披露——将领域特定规则移至单独文件
指令冲突	检查矛盾并解决
Agent查找位置错误	描述能力，而非文件路径
随着时间推移出现混合约定	将AGENTS.md视为活文档，定期审核

AGENTS.md vs CLAUDE.md

AGENTS.md与CLAUDE.md

Claude Code uses

CLAUDE.md

instead of

AGENTS.md

. To maintain compatibility:

bash

undefined

Claude Code使用

CLAUDE.md

而非

AGENTS.md

。为保持兼容性：

bash

undefined

Create a symlink from AGENTS.md to CLAUDE.md

创建AGENTS.md到CLAUDE.md的符号链接

ln -s AGENTS.md CLAUDE.md


Both files serve the same purpose - customize how AI coding agents behave in your repository.

ln -s AGENTS.md CLAUDE.md


两个文件的用途相同——自定义AI编码Agent在你的仓库中的行为。

Tools Supporting AGENTS.md

支持AGENTS.md的工具

AGENTS.md is an open standard supported by many tools:

OpenAI Codex, Jules (Google), Factory, Aider, goose, opencode
VS Code, Devin (Cognition), Cursor, RooCode, Gemini CLI
GitHub Copilot coding agent, Windsurf (Cognition), and more

See https://agents.md/ for the full list.

AGENTS.md是一个开放标准，已得到众多工具支持：

OpenAI Codex、Jules（Google）、Factory、Aider、goose、opencode
VS Code、Devin（Cognition）、Cursor、RooCode、Gemini CLI
GitHub Copilot编码Agent、Windsurf（Cognition）等

完整列表请查看https://agents.md/。

Your Approach

你的实施步骤

Start minimal: Begin with essential information only
Apply progressive disclosure: Move domain-specific rules to separate files
Avoid file paths: Describe capabilities, not structure
Keep it conversational: Use natural language, not rigid commands
Review periodically: Treat as living documentation
Use nested files: For monorepos, place AGENTS.md in subdirectories
Link, don't duplicate: Point to other resources instead of repeating

从简洁开始：仅保留必要信息
应用渐进式披露：将领域特定规则移至单独文件
避免文件路径：描述能力，而非结构
保持对话式语气：使用自然语言，而非生硬命令
定期审核：将其视为活文档
使用嵌套文件：对于单体仓库，在子目录中放置AGENTS.md
链接而非重复：指向其他资源，不要重复内容

Progressive Disclosure

渐进式披露

Deep dive on specific topics:

Verification checklist: VERIFICATION.md
Refactoring guide: REFACTORING.md
Template gallery: TEMPLATES.md
Monorepo patterns: MONOREPO.md
Common anti-patterns: ANTI_PATTERNS.md

特定主题的深入内容：

验证清单：VERIFICATION.md
重构指南：REFACTORING.md
模板库：TEMPLATES.md
单体仓库模式：MONOREPO.md
常见反模式：ANTI_PATTERNS.md