GEMINI.md vs AGENTS.md: do you need both?
No. Keep your instructions in AGENTS.md and point Gemini CLI at it: list it in context.fileName, or make GEMINI.md one line, @AGENTS.md.
How do they differ?
- Where
- GEMINI.md:
~/.gemini/GEMINI.md, the workspace and its parent directories, and a directory's own file once a tool reaches it. - AGENTS.md: The repo root, and any subdirectory, depending on the agent.
- Imports
- GEMINI.md:
@file.md, relative or absolute, up to 5 levels deep. - AGENTS.md: None; it's plain markdown.
- Change the file name
- GEMINI.md:
context.fileNameinsettings.jsontakes one name or a list. - AGENTS.md: Fixed by each agent.
- Repos with one
- GEMINI.md: 8 of 401 (2%)
- AGENTS.md: 203 of 401 (51%)
7 of the 8 repos with GEMINI.md also have an AGENTS.md or CLAUDE.md. Empty files don't count.
How do I use both?
- Keep the instructions in AGENTS.md.
- Commit
.gemini/settings.jsonwith the setting below; project settings override a user's. - Or add a GEMINI.md containing
@AGENTS.md, which also passes our check. - Run
/memory showin Gemini CLI to see what it loaded.
What does it look like?
Gemini CLI · .gemini/settings.json
{
"context": {
"fileName": [
"AGENTS.md",
"GEMINI.md"
]
}
}
From the docs: geminicli.com/gemini-md · geminicli.com/configuration · geminicli.com/memport · agents.md
How we score GEMINI.md · AGENTS.md vs CLAUDE.md · Make a repo agent-ready