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

[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.