Gemini CLI and Antigravity setup: AGENTS.md, skills, rules

Q: Does Gemini CLI read AGENTS.md?

Not by default. It reads GEMINI.md. Set context.fileName in .gemini/settings.json to a list that includes AGENTS.md, like ["AGENTS.md", "GEMINI.md"], and it loads both.

Q: Where do Antigravity skills go?

In .agents/skills/ /SKILL.md, the Agent Skills folder most other agents read too. Run one as /name.

Q: Does Gemini CLI support hooks?

Yes. Hooks live under hooks in .gemini/settings.json. A BeforeTool hook that exits 2 blocks the tool call. Project hooks run only in a trusted folder.

Google has two coding agents, and they set up differently. Gemini CLI reads GEMINI.md unless you point it at AGENTS.md. Antigravity reads AGENTS.md and the shared .agents/ folder as they are.

Which one you use depends on your account. On 2026-06-18, consumer accounts (free, Pro and Ultra) moved from Gemini CLI to Antigravity CLI. Gemini CLI still works with paid API keys and Code Assist.

Below: both setups, with the real files from a generated Next.js repo.

The two side by side

	Gemini CLI	Antigravity
Instructions	GEMINI.md. AGENTS.md through `context.fileName`	AGENTS.md and GEMINI.md, root and nested
Rules	Inside the instruction files	`.agents/rules/*.md`, each with a `trigger`
Skills	`.agents/skills/`	`.agents/skills/`, run as `/name`
Subagents	`.gemini/agents/*.md`	`.agents/agents/*.md`
Hooks	`hooks` in `.gemini/settings.json`	`.agents/hooks.json`
MCP	`mcpServers` in `.gemini/settings.json`	`.agents/mcp_config.json`

Gemini CLI

GEMINI.md vs AGENTS.md

Gemini CLI loads GEMINI.md by default. The context.fileName setting changes which file names it loads, and it takes a list. So you don't need a GEMINI.md at all: list AGENTS.md and Gemini CLI reads the same file every other agent reads.

The generated .gemini/settings.json does exactly that, and holds the hooks and MCP servers too:

{
  "$schema": "https://raw.githubusercontent.com/google-gemini/gemini-cli/main/schemas/settings.schema.json",
  "context": {
    "fileName": [
      "AGENTS.md",
      "GEMINI.md"
    ]
  },
  "hooks": {
    "AfterTool": [
      {
        "matcher": "replace|write_file",
        "hooks": [
          {
            "name": "auto-lint",
            "type": "command",
            "command": "bun $GEMINI_PROJECT_DIR/.agents/hooks/run.mjs auto-lint --from gemini",
            "timeout": 60000
          },
          {
            "name": "enforce-doc-meta",
            "type": "command",
            "command": "bun $GEMINI_PROJECT_DIR/.agents/hooks/run.mjs enforce-doc-meta --from gemini",
            "timeout": 60000
          },
          {
            "name": "env-leak-detector-write",
            "type": "command",
            "command": "bun $GEMINI_PROJECT_DIR/.agents/hooks/run.mjs env-leak-detector-write --from gemini",
            "timeout": 60000
          }
        ]
      }
    ],
    "BeforeTool": [
      {
        "matcher": "grep_search|read_file|read_many_files|run_shell_command",
        "hooks": [
          {
            "name": "env-leak-detector",
            "type": "command",
            "command": "bun $GEMINI_PROJECT_DIR/.agents/hooks/run.mjs env-leak-detector --from gemini",
            "timeout": 60000
          }
        ]
      },
      {
        "matcher": "run_shell_command",
        "hooks": [
          {
            "name": "block-destructive",
            "type": "command",
            "command": "bun $GEMINI_PROJECT_DIR/.agents/hooks/run.mjs block-destructive --from gemini",
            "timeout": 60000
          },
          {
            "name": "enforce-typecheck",
            "type": "command",
            "command": "bun $GEMINI_PROJECT_DIR/.agents/hooks/run.mjs enforce-typecheck --from gemini",
            "timeout": 60000
          },
          {
            "name": "guard-neon-sql",
            "type": "command",
            "command": "bun $GEMINI_PROJECT_DIR/.agents/hooks/run.mjs guard-neon-sql --from gemini",
            "timeout": 60000
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "better-auth": {
      "httpUrl": "https://mcp.better-auth.com/mcp"
    },
    "neon": {
      "httpUrl": "https://mcp.neon.tech/mcp?readonly=true"
    },
    "posthog": {
      "httpUrl": "https://mcp.posthog.com/mcp?readonly=true"
    },
    "sentry": {
      "httpUrl": "https://mcp.sentry.dev/mcp"
    },
    "stripe": {
      "httpUrl": "https://mcp.stripe.com"
    }
  }
}

.gemini/settings.json, as generated.

fileName lists AGENTS.md first, then GEMINI.md. No GEMINI.md ships. Add one later for Gemini-only notes, and it loads next to AGENTS.md.

Hooks

The hooks block in that file holds the guards. BeforeTool fires before a tool runs and can block it. AfterTool fires after it. Matchers use Gemini's tool names: run_shell_command, read_file, write_file, replace.

One launcher. Each hook runs .agents/hooks/run.mjs <guard> --from gemini, from $GEMINI_PROJECT_DIR, the project root. It turns Gemini's payload into the format the guards speak.
Exit 2 blocks, and the reason goes back to the agent.
timeout is in milliseconds here. 60000 is one minute.
Trust first. Gemini CLI runs a project's hooks, MCP servers and subagents only in a folder you trust.

Two limits outside Claude Code: a rewrite becomes a block that names the command to run instead, and hiding a secret in command output doesn't happen. More: guard hooks in every agent.

Subagents

Gemini CLI reads subagents from .gemini/agents/, one markdown file each, with a name, a description and a tool list in the frontmatter. The top of the generated PR reviewer:

---
description: Reviews a diff against this repo's rules before it becomes a PR. Convention-aware, blocking on correctness and security, advisory on taste.
name: pr-reviewer
tools:
  - read_file
  - read_many_files
  - grep_search
  - glob
  - list_directory
  - run_shell_command
---

First 11 of 92 lines of .gemini/agents/pr-reviewer.md.

No write_file and no replace, so the reviewer reads and runs checks but can't edit. Send a task straight to one with @pr-reviewer at the start of your prompt.

MCP and skills

The mcpServers block lists remote servers with httpUrl. Sign in to one with /mcp auth <server>. Neon and PostHog connect read-only.

Gemini CLI reads skills from .agents/skills/. We checked on Gemini CLI 0.63. Ask for one by name, like "run the setup skill". The Compound Engineering plugin has no Gemini CLI install path yet. The repo's own 29 skills work either way.

Antigravity

AGENTS.md and .agents/rules

Antigravity reads AGENTS.md and GEMINI.md at the root and in subfolders. They need no frontmatter, and each stays active for its folder.

It also reads rule files from .agents/rules/. Each one must start with a trigger: always_on, glob, model_decision or manual. A file without a valid trigger is dropped. Antigravity caps a rule file at 24 KB, and always-on rules share a 20,000-token budget.

A generated repo puts every rule in .agents/rules/ in full, and sets each trigger so nothing loads twice:

A rule the AGENTS.md files carry in full gets trigger: manual. Antigravity already has it from them.
A rule some AGENTS.md only links to (its folder ran out of room) gets trigger: glob, for exactly the folders where it was linked.

The Stripe webhook rule is the second kind:

---
description: Verify every Stripe webhook, keep every handler idempotent
globs: src/lib/billing/provider.ts, src/lib/billing/webhook.ts
trigger: glob
---

# Verify every Stripe webhook, keep every handler idempotent

Applies to: `src/app/api/webhooks/stripe/**`, `src/lib/billing/provider.ts`, `src/lib/billing/webhook.ts`

First 9 of 72 lines of .agents/rules/stripe-webhook-integrity.md.

Skills and subagents

Antigravity reads Agent Skills from .agents/skills/ and runs them as /name. Start with /setup on a fresh clone. Subagent prompts come from .agents/agents/: a name, a description and the prompt. Both folders ship in every generated repo, so Antigravity needs no copies.

Hooks: .agents/hooks.json

Antigravity reads workspace hooks from .agents/hooks.json. Each hook has a name, and each name maps to its events. Matchers use Antigravity's tool names: run_command, view_file, write_to_file, replace_file_content. The first two guards in the generated file:

{
  "auto-lint": {
    "PostToolUse": [
      {
        "matcher": "multi_replace_file_content|replace_file_content|write_to_file",
        "hooks": [
          {
            "type": "command",
            "command": "bun .agents/hooks/run.mjs auto-lint --from antigravity",
            "timeout": 60
          }
        ]
      }
    ]
  },
  "block-destructive": {
    "PreToolUse": [
      {
        "matcher": "run_command",
        "hooks": [
          {
            "type": "command",
            "command": "bun .agents/hooks/run.mjs block-destructive --from antigravity",
            "timeout": 60
          }
        ]
      }
    ]
  },

First 29 of 100 lines of .agents/hooks.json.

The launcher reads Antigravity's payload, where the call arrives as toolCall, and answers with decision: "deny" and a reason when a guard blocks. The same two limits apply as in Gemini CLI.

MCP: .agents/mcp_config.json

{
  "mcpServers": {
    "better-auth": {
      "serverUrl": "https://mcp.better-auth.com/mcp"
    },
    "neon": {
      "serverUrl": "https://mcp.neon.tech/mcp?readonly=true"
    },
    "posthog": {
      "serverUrl": "https://mcp.posthog.com/mcp?readonly=true"
    },
    "sentry": {
      "serverUrl": "https://mcp.sentry.dev/mcp"
    },
    "stripe": {
      "serverUrl": "https://mcp.stripe.com"
    }
  }
}

.agents/mcp_config.json, as generated.

Remote servers use serverUrl. Approve each tool the first time it runs. Local servers that need a key, like Postmark or Supabase, are left out of this file: it has no safe way to read a variable. SETUP.md says so.

Install the Compound Engineering plugin with agy plugin install https://github.com/EveryInc/compound-engineering-plugin.

Setup checklists

Gemini CLI:

Open the repo and trust the folder.
Ask for the setup skill. It fills .env.local and connects the services, after you say yes.
Sign in to each MCP server with /mcp auth <server>.
Run bun run verify:hooks to see every guard block in Gemini's format.

Antigravity:

Open the repo and run /setup.
Approve each MCP tool the first time it runs.
Install the plugin with the agy command above.
Run bun run verify:hooks to see every guard block in Antigravity's format.

Get a repo that works in both

Pick your stack at /build. Gemini CLI and Antigravity are two of 10 agents, all on by default. You get AGENTS.md and its nested files, .agents/ with every rule, skill, subagent and guard, .gemini/ for Gemini CLI, and Antigravity's hook and MCP files. The same repo works in Claude Code, Codex, Cursor, Copilot and the rest. $99 once, with lifetime updates. What each agent gets: the agentic layer.

More: AGENTS.md examples, Agent Skills in every agent, CLAUDE.md vs AGENTS.md.

FAQ

Does Gemini CLI read AGENTS.md?

Not by default. It reads GEMINI.md. Set context.fileName in .gemini/settings.json to a list that includes AGENTS.md, like ["AGENTS.md", "GEMINI.md"], and it loads both.

Should I use GEMINI.md or AGENTS.md?

AGENTS.md, if any other agent works in the repo. Gemini CLI reads it once context.fileName lists it, and Antigravity reads both names. Keep GEMINI.md for Gemini-only notes.

Where do Antigravity rules go?

In AGENTS.md files, root and nested, with no frontmatter. Or in .agents/rules/, one .md file each, starting with a trigger: always_on, glob, model_decision or manual.

Where do Antigravity skills go?

In .agents/skills/<name>/SKILL.md, the Agent Skills folder most other agents read too. Run one as /name.

Does Gemini CLI support hooks?

Yes. Hooks live under hooks in .gemini/settings.json. A BeforeTool hook that exits 2 blocks the tool call. Project hooks run only in a trusted folder.

Can I still use Gemini CLI?

Yes, with a paid API key or Code Assist. Free, Pro and Ultra consumer accounts moved to Antigravity CLI on 2026-06-18.

Sources

Tool behavior is from the official docs, checked on October 8, 2026. Tools change. The docs win.

Gemini CLI and Antigravity setup with AGENTS.md