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.fileName in settings.json takes 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%)
Agents that read it
GEMINI.md: 1 of 9: Gemini CLI
AGENTS.md: 6 of 9; which ones

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?

  1. Keep the instructions in AGENTS.md.
  2. Commit .gemini/settings.json with the setting below; project settings override a user's.
  3. Or add a GEMINI.md containing @AGENTS.md, which also passes our check.
  4. Run /memory show in 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