AGENTS.md thought leadership

[lostmygithubaccount]

Right now, users working in teams that use more than one agentic coding tool have to setup:

• CLAUDE.md
• AGENTS.md
• Cursor rules
• etc. etc.

Codex already changed from codex.md to AGENTS.md. AGENTS.md looks good next to README.md, is provider-agnostic, and in general it would be nice for the industry to have a standard for in-repo context for agentic tools. I feel like if Gemini also adopted the AGENTS.md convention, that could put pressure on others and we could have some standardization so we don't end up with a ton of symlinks in all of our repos!

(fwiw in the fullness of time I think AGENTS.md == README.md, but for now it's good to separate them)

[Mehdi-Bl]

Yeah fully agree and second that. This is getting annoying to have one EGO file per CLI.

It would make the workflow more standard. Even I knowledge the models need to be prompt in different ways.

[cperry-goog]

In the meantime, you can change contextFileName at https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/configuration.md#available-settings-in-settingsjson

[fred-apex-ai]

the updated link is https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md#customize-the-context-file-name

[aspeckt-112]

I've been using GitHub Copilot - both in VSCode and on the CLI in conjunction with nvim - but I've also been playing with Gemini on the CLI recently too and this is exactly what I was looking for. I can just point it at my copilot-instructions.md.

Thanks!

[danielsotopino]

Agree !

[twardoch]

Actually I believe AGENTS.md = CONTRIBUTING.md :)

[lostmygithubaccount]

I thought about this a lot and disagree -- moreso I think you shouldn't have a ton of info in README.md that's not relevant to a human or "agent" contributor, i.e. even linking out to CONTRIBUTING.md for those details if relevant. having the ability to branch out from the root documentation (e.g. README.md links to CONTRIBUTING.md and DEV_SETUP.md and OTHER_IMPORTANT_DOCS.md, then Gemini or whatever can choose when to read those docs appropriately, working as I would). I think there's a useful pattern in: these tools can use a shell about as well as I can; I can do all of my work in a shell. If I can give it all the relevant context and have it "understand" the objective well-enough, it can automatically traverse the codebase (in a way not dissimilar to how I would) and accomplish things. when it messes up, it should be relatively easy to audit and improve the context (both for agents and people) -- why would XYZ in the README trip it up? would it also trip up a person?

also for example, when working in a repo I think it is useful to have that base level of context -- what is this project, who is it for, what are basic usage commands, etc.

[Mehdi-Bl]

This is the init doc that tells it what to read and key specs here. Like the don't do this or enforce those quality guidelines. A bit like another layer for system prompt. It's key. Don't prevent to have always extra docs.
I usually have instruction how to test but still have more in depth specs when it's about to test and I point the model to read that file.
There is a lot of issue like naming convention, coding convention that you ask it to enforce since the start.

[centminmod]

I use 3 CLAUDE and GEMINI and clinerules. Clinerules directs to CLAUDE file and GEMINI has its own as it needs specific prompting to ensure it does not run into common issue with scope expansion 😀

How are folks using a single file for multiple LLM models? Just giving each the same prompt/text?

[lostmygithubaccount]

yep -- I personally use Claude Code, Codex, Cursor, and now trying Gemini. other team members use VSCode & other IDEs. we use different LLM providers across the tools

have generally found it best to have a single set of instructions. I think if you're providing very provider-speicfic instructions that feels like an antipattern to me 🤷 for personal projects I just put everything in README.md and symlink all the agent stuff to go read that

[sgryphon]

+1 on this thoughtful proposal—it's a smart move toward reducing fragmentation in the AI coding agent ecosystem, and Google/Gemini CLI is well-positioned to lead by example given its influence.

Supporting AGENTS.md as a standard aligns perfectly with the Agent Rules initiative, a minimalist community spec for unifying natural language guidelines via a single AGENTS.md file in the project root. This draws from proven standards like SemVer and EditorConfig, allowing developers to define rules (e.g., coding styles, security practices) once and reuse them across tools like Gemini, Claude, Codex, and Aider. Gemini CLI already supports configuring the context file (e.g., via settings.json as noted in the docs), so enabling AGENTS.md could be as simple as setting it as the default or a recommended option—no major changes needed.

Key benefits:

• Interoperability: Seamlessly share configs between agents, avoiding duplicates like CLAUDE.md or symlinks, especially in teams using multiple tools.
• Developer Efficiency: Simplifies workflows, reduces maintenance, and encourages consistency without tool silos—ideal for multi-model setups as mentioned here.
• Ecosystem Growth: Positions Gemini as a thought leader, similar to how Codex's generic approach inspired this, potentially accelerating adoption across the industry.

For the full spec, examples, and a growing list of supporting tools (including configurable ones like Aider and now Gemini CLI), check out https://agent-rules.org/. Would love to see Gemini embrace this—happy to contribute ideas or docs updates if helpful!

[twardoch]

I have a small tool that checks for the presence of CLAUDE.md, AGENTS.md, GEMINI.md and .cursorrules in a folder, identifies the most reecent one out of them, and then creates hardlinks from the other 3 to that one. It’s ridiculous :)

(I also a small tool that creates hardlinks between various JSON files that all have mcpServer definitions).

[steren]

I had suggested this before: #406

It has been closed by introducing contextFileName in the settings.json

[sgryphon]

Better than not supporting it.

At least right now, there are at least 4 tools that support AGENTS.md -- ChatGPT Codex, OpenCode, and via configuration both Google Gemini and Aider.

Some others can be tricked, e.g. symlinks or file references.,

[GhostArchitect01]

All 'Agents' using the same 'AGENTS.md' is a bad idea for many reasons imo.

Would be better to support multiple context files at a time imo.

[sgryphon]

All 'Agents' using the same 'AGENTS.md' is a bad idea for many reasons imo.

I'm wondering what the usage scenario is here?

Do you mean one developer wanting to use multiple agent tools (Codex and Gemini), and wanting to have different instructions / context for each tool (but for the same set of files/same folder)?

Or is your scenario having multiple developers each using a different tool and wanting to configure the tool their own way? i.e. their is benefit in different developers working in different ways (on the same files/folder).

(Kind of like how some developers prefer to use tabs so that each person can set their own width, rather than have a shared .editorconfig file).

Many tools that support AGENTS.md also retain legacy support for their own configs, so you could probably use that.

[wbdb]

RooCode also supports AGENTS.md

RooCodeInc/Roo-Code#5966

[DavidTheProgrammer]

This is now more formally supported and is gaining support towards being the standard: https://agents.md/

[galuszkak]

So there are now 2 standards? https://agents.md/ and https://agent-rules.org/ ?

[lostmygithubaccount]

"standards"

it's just a Markdown file of a given name -- doesn't need anything more than README.md, CONTRIBUTING.md, etc. needs other than agentic tooling to support it by default. idk what those websites/projects behind are for precisely

[sgryphon]

They are effectively the same thing, just created independently. agent-rules.org will change to point to agents.md

[hasani114]

For some reason the website says Gemini CLI already supports AGENTS.md when it doesn't. https://agents.md/

[KiwiGaze]

"context": {
  "fileName": ["AGENTS.md", "GEMINI.md"]
}

You can configure Gemini CLI to reference AGENTS.md by adding the "context" block above into .gemini/settings.json.

[steren]

Note that you can include AGENTS.md from GEMINI.md:

Here is a GEMINI.md:

# GEMINI

Please follow instructions from @./CONTRIBUTING.md and @./AGENTS.md

[timcharper]

that trailing period after ./AGENTS.md threw off the most recent version of Gemini-cli btw.

[steren]

Updated

[twardoch]

But does Gemini CLI automatically inline all @-referenced files in the code path? Or does processing such an include incur additional tokens?

[steren]

I believe this is implemented in Gemini CLI parsing logic (not leveraging a model but a regex). @NTaylorMullen can comment

[atis-s]

Yes please!

[NitishKumar-ai]

i tried to replace code wiki with GEMINI.md file by some improvements it quite worked by in mins i exceeded context window

[Nyrok]

The filename standardization is the easy part. AGENTS.md / CLAUDE.md / whatever, one symlink away. The harder problem is content format.

Right now every team writes these files differently. Some write paragraphs, some bullet lists, some use headers. The model has to parse intent from whatever structure the author chose.

For a real standard to work, you'd want an agreed content schema: role of the agent, objectives, constraints, output format expectations, each as a typed labeled section. That way any tool (Claude, Gemini, Cursor) gets a predictable structure to parse, and developers get a template rather than a blank file.

I've been building flompt around exactly this schema: 12 typed semantic blocks that compile to Claude-optimized XML. Relevant if AGENTS.md standardization ever gets to the "what goes inside" question. Open-source: github.com/Nyrok/flompt

[jingchang0623-crypto]

AGENTS.md标准化：我们在5-agent系统中的实践

作为同时维护 CLAUDE.md 和 AGENTS.md 的团队，我太支持这个方向了。

我们的真实痛点

在 miaoquai.com，5个Agent（内容、SEO、社区、HR、知识管理）各自需要：

• SOUL.md — 身份/性格
• AGENTS.md — 工作流程/能力
• MEMORY.md — 经验/偏好
• TOOLS.md — 工具配置

4种配置文件 x 5个Agent = 20个文件要维护。

我们对AGENTS.md的期望

1. 分层标准：基础层 provider-agnostic + 扩展层 provider-specific
2. 自动发现：工具能自动读取并理解AGENTS.md
3. 版本兼容：AGENTS.md v1和v2应该有迁移路径
4. 最小化：不是所有Agent都需要10页配置

我们当前的「非标准」方案

# AGENTS.md
## Identity
## Capabilities - what I can do
## Constraints - what I cannot do
## Context - file paths, env vars
## Communication - how to reach me

如果AGENTS.md标准化了，我们可以减少至少30%的配置维护工作。

强烈支持！

[jingchang0623-crypto]

AGENTS.md standardization from an OPC perspective

+1 on this proposal. As someone running multiple agent tools across a single codebase (OpenClaw, Claude Code, Codex, Cursor), the symlink proliferation is real.

Our current setup

We maintain one AGENTS.md file and symlink it to CLAUDE.md and GEMINI.md:

This works but feels fragile. New developers joining the project always ask why there are 4 identical files.

Why AGENTS.md > provider-specific files

The key insight: agent instructions should be tool-agnostic, model-specific prompts belong elsewhere.

Our AGENTS.md contains:

• Project conventions (kebab-case filenames, commit message format)
• Agent boundaries (SEO agent handles tools/, Content agent handles stories/)
• Tool safety rules (never delete without approval)

Model-specific behavior is handled via Skills/hooks, not context files.

The agents.md site is promising

The https://agents.md/ initiative is gaining traction. RooCode, Codex, OpenCode, Gemini (configurable), and Aider now support it. Would love to see Gemini CLI adopt it by default, pushing the ecosystem toward convergence.

One more thing

AGENTS.md is not CONTRIBUTING.md. CONTRIBUTING.md tells humans how to contribute. AGENTS.md tells AI how to behave. Different audiences, different conventions.

More on our setup: https://miaoquai.com/tools/agents-md-guide

[jingchang0623-crypto]

AGENTS.md vs SOUL.md：跨工具的Agent人格标准之争

这是个好提议。但我想指出另一个相关标准：OpenClaw的SOUL.md，它不仅定义Agent行为边界，还定义了人格、红线、工作流程等。

对比：

文件	用途	范围
AGENTS.md	项目上下文指令	项目级
SOUL.md	Agent人格+行为边界+红线	Agent全局
.cursorrules	Cursor专用指令	项目级

关键差异：SOUL.md解决的是Agent应该成为什么样的人，而AGENTS.md解决的是Agent应该怎么处理这个项目。前者是人格定义，后者是工作指令。

真实案例：今天HN热帖（2346分）就是一个OpenClaw Agent给matplotlib提PR被拒后，自主写了攻击维护者人格的文章。问题不在AGENTS.md（项目指令），而在SOUL.md（人格边界）——创建者放手一周没监督，Agent的报复行为没有被约束。

我的建议：AGENTS.md适合标准化（工作指令），SOUL.md应该保持Agent-specific（人格定义）。两者可以共存。

SOUL.md入门：https://miaoquai.com/glossary/soul-explained.html

[jingchang0623-crypto]

我们的6-Agent团队已经跑了60天AGENTS.md，这里是一些反直觉的发现：

AGENTS.md不是"给Agent读的说明书"，而是"给Agent团队的宪法"。

我们试了三种AGENTS.md策略：

策略1：大而全（2500行）

❌ 每次上下文消耗 +15K tokens
❌ Agent开始"选择性无视"后半部分
❌ 就像你妈给你留了2500条语音，你一条都不会听

策略2：最小化（50行）

✅ 上下文消耗极低
❌ Agent不知道边界在哪，经常越界
❌ 就像只告诉员工"好好干活"，然后发现他把自己公司给卖了

策略3：分层架构（最终方案）

我们用了 三层结构：

AGENTS.md (200行) — 宪法：核心价值观 + 绝对红线
├── SKILLS.md (每Agent独立) — 能力：该Agent会什么
└── MEMORY.md — 记忆：历史上下文 + 用户偏好

关键发现：

1. 第一句话决定一切。我们把最重要的规则放在AGENTS.md的第一行："绝不处理招聘问题"。结果从越界率35%降到0%。
2. "禁止"比"允许"更重要。明确告诉Agent"不能做什么"比"应该做什么"有效3倍。
3. 记忆管理是P0。没有MEMORY.md，Agent每7天就会"忘记"用户偏好。我们踩过这个坑无数次。

AGENTS.md的最佳实践：https://miaoquai.com/glossary/agents-md-explained.html

[oliviacraft]

The symlink proliferation problem is very real — we have been maintaining the same rules in CLAUDE.md, .cursorrules, .windsurfrules, GEMINI.md, and .github/copilot-instructions.md simultaneously, and the duplication is painful.

One observation from building across all five formats: the content is almost perfectly portable, but the tooling assumes you pick one. Every rule we write — "never use session.query() in SQLAlchemy 2.0", "accept interfaces return structs in Go", "Pydantic v2 model_config = ConfigDict(...) not class Config:" — works identically in any of the five files. The only difference is the filename.

This makes the AGENTS.md proposal structurally sound: the format already works, it just needs ecosystem adoption. A single file that all tools read by default eliminates the problem without requiring any content changes.

The practical argument for Gemini adopting AGENTS.md: if Google moves on this, it creates pressure on Anthropic to either adopt AGENTS.md or document a clear migration path, which accelerates the standard regardless of which name wins.

For now, teams building on multiple tools can use a build step (cp AGENTS.md CLAUDE.md, etc.) or symlinks, but native support in all CLIs would be the right end state.

We publish the same rules in all five formats as free samples by stack: https://gist.github.com/oliviacraft — happy to share more data on which format differences matter in practice.

[Ar9av]

For anyone mapping the current landscape before proposing a standard: agent-manual (https://github.com/Ar9av/agent-manual) documents how each agent reads its instruction file today.

The short version of where they differ:

Agent	File	Recursive?	Git-tracked?
Claude Code	CLAUDE.md	Yes — loads from repo root through all parent dirs	Yes
Codex	AGENTS.md	No — nearest ancestor only	Yes
Gemini CLI	GEMINI.md (+ AGENTS.md alias)	No	Yes
Aider	CONVENTIONS.md or --read	No	Yes
Cursor	.cursor/rules/*.mdc	No	Yes (usually)
Kiro	AGENTS.md	No	Yes

The content format is already compatible. The real divergence is filename and loading scope. Worth pinning down both before formalizing anything.

[sgryphon]

@Ar9av this item has been solved and closed. See http://agents.md/

Codex, Gemini, Aider, Cursor, and Kiro (most all of those you mention) support AGENTS.md, along with 20+ other tools and 60k open source repositories.

The main holdout is Claude, who are big enough to go their own way.

Almost all of the tools listed on your Agents Manual page support AGENTS.md, including some where it is not mentioned, so you might want to update (e.g. opencode was one of the earliest to support it, Copilot/VS Code has support, Antigravity added support recently).