Google Antigravity and AGENTS.md: The Complete 2026 Guide

Google Antigravity is Google’s agent-first IDE — built around giving an autonomous agent a task and reviewing its work, rather than typing every line yourself. Since IDE version 1.20.5, it also reads AGENTS.md. Before that release, it only understood its own GEMINI.md convention; the changelog entry is blunt about it — “Added support for reading rules from AGENTS.md in addition to GEMINI.md.”

AGENTS.md is a Markdown file that AI coding agents read for project-specific instructions — build commands, conventions, and the kind of context a human-facing README doesn’t carry. In Antigravity, this content is called a Rule, and Rules are only one of three separate customization systems the product ships: Rules for standing instructions, custom agent.md files for defining named agents, and SKILL.md files for on-demand capabilities. They don’t overlap the way their names suggest, and mixing them up is the easiest way to write a Rule that never actually loads.

Where Antigravity Looks for Rules

Per Antigravity’s own docs, two locations are checked automatically:

• Global: ~/.gemini/GEMINI.md — applies across every workspace you open, no per-project setup.
• Workspace: a .agents/rules folder in the project root. Antigravity’s docs note this is now the default location, with .agent/rules (singular, no s) kept working for backward compatibility if that’s what an older project already has.

A single root-level GEMINI.md or AGENTS.md file also works — the changelog language for 1.20.5 describes the agent reading both directly, and Google’s docs confirm the agent “automatically consults and enforces your global constraints located at ~/.gemini/GEMINI.md” on top of whatever’s in the active directory. In practice that gives you two valid setups: a single file at the workspace root for a small project, or a .agents/rules/ folder of multiple files for anything that benefits from splitting rules by topic.

Each Rules file is capped at 12,000 characters. That’s generous compared to some tools, but it’s a hard limit worth knowing before you paste in an entire style guide and wonder why half of it gets ignored.

Rules vs Workflows — Not the Same Thing

Antigravity’s docs draw a specific line here: “While Rules provide models with guidance by providing persistent, reusable context at the prompt level, Workflows provide a structured sequence of steps or prompts at the trajectory level, guiding the model through a series of interconnected tasks or actions.” A Rule is standing context — coding conventions, stack details, things that are true on every task. A Workflow is a repeatable procedure — deploying a service, responding to PR comments — something with steps, not just facts. If you’re trying to get Antigravity to reliably execute a multi-step process, that belongs in a Workflow file, not a Rule; padding a Rule with step-by-step instructions is fighting the tool’s own model of what each file is for.

Pulling In Other Files with @-Mentions

Rules files support @filename references to include other files without pasting their content inline. The resolution order, per Google’s docs:

• A relative path resolves relative to the location of the Rules file doing the mentioning.
• An absolute path resolves as a true absolute path.
• An @/-style reference — written as if absolute but meant to be workspace-relative — is first tried as a literal absolute path, and if that file doesn’t exist, Antigravity falls back to resolving it against the workspace root.

That fallback behavior is easy to get backwards: @/docs/style.md isn’t guaranteed to mean “the docs/style.md inside my workspace” unless a file literally named /docs/style.md doesn’t exist at the filesystem root first.

Custom Agents: agent.md Files

Separately from Rules, Antigravity CLI (as of 1.1.6) lets you define named custom agents as Markdown files with YAML frontmatter and an H1-delimited system prompt. The documented frontmatter fields:

A minimal example, based on the documented fields:

---
subagent: true
mainAgent: false
model: pro
commandExecutionPolicy: sandbox
---
# Code Auditor

Review the diff for correctness and security issues. Do not modify
files — report findings only. Flag anything touching auth, secrets,
or database migrations for explicit human review.

The CLI’s --agent flag (added in 1.1.1) lets you select which custom agent runs at launch, and agent/agents subcommands list what’s available. This is a different mechanism from Claude Code’s subagents or Amp’s system-wide config tiers — it’s closer to defining named personas with their own model, permissions, and MCP access, then dispatching work to the right one by name.

Skills: SKILL.md Files

Agent Skills — added in IDE 1.14.2 — are Antigravity’s third customization layer, and the one most similar to what Claude Code and other tools call Skills. Each skill is a folder containing a required SKILL.md with YAML frontmatter (description is required, name is optional), plus optional scripts/, examples/, and resources/ subfolders. Two locations are checked:

• Workspace: .agents/skills/<skill-folder>/SKILL.md
• Global: ~/.gemini/config/skills/<skill-folder>/

Google’s docs describe a three-stage progressive disclosure model: at session start, the agent sees only each skill’s name and description (Discovery). If a task looks relevant, it reads the full SKILL.md content (Activation). Only then does it follow the instructions during actual work (Execution). You don’t have to invoke a skill by name — “you don’t need to explicitly tell the agent to use a skill—it decides based on context” — though you can reference one directly if you want to force it. The documented best practice is writing descriptions in the third person with task-relevant keywords, since that description is the only thing the agent sees before deciding whether a skill is worth reading in full.

Two Agent Settings Worth Knowing

Antigravity’s Agent Settings page documents exactly two autonomy controls — worth stating precisely, since some third-party write-ups describe a longer list of named “autonomy profiles” that don’t appear in Google’s own docs:

1. Terminal Command Auto Execution — either “Request Review” (commands need approval except an allowlist) or “Always Proceed” (commands run automatically except a denylist).
2. Agent Non-Workspace File Access — off by default, meaning the agent can only touch files inside your project plus the app’s local data directory. Turning it on lets the agent read and edit files outside the workspace, which Google’s own docs caution against for exactly the reason you’d expect: it widens what a misfired command or bad instruction can reach.

How This Compares to Other Tools

The structural takeaway: Antigravity, Claude Code, and Cursor all converge on AGENTS.md as a readable baseline, but each layers its own tool-specific system on top — Antigravity’s .agents/rules folder and agent.md personas, Claude Code’s subagent directory, Cursor’s .mdc rule files with their own frontmatter. An AGENTS.md written for portability works everywhere; anything you want Antigravity-specific — a sandbox-only subagent, a Skill folder — has to live in Antigravity’s own structure.

FAQ

Q1. Does Google Antigravity read AGENTS.md automatically, or does it need configuration? Automatically, as of IDE version 1.20.5. No setup is required beyond having the file in your workspace; Antigravity’s changelog documents this as “support for reading rules from AGENTS.md in addition to GEMINI.md.”

Q2. What’s the difference between GEMINI.md and AGENTS.md in Antigravity? Both are read as Rules. GEMINI.md is Antigravity’s original, Gemini-specific convention with a dedicated global path (~/.gemini/GEMINI.md); AGENTS.md is the cross-tool standard also read by Claude Code, Cursor, and others. Google’s own docs describe the agent consulting both a workspace file and the global GEMINI.md together — they haven’t documented a strict override order between GEMINI.md and AGENTS.md when both exist at the same level, so treat that combination as untested rather than assume either wins.

Q3. Is there a size limit on Antigravity Rules files? Yes — 12,000 characters per file, for both Rules and Workflows.

Q4. What’s the difference between a Rule, a Workflow, an agent.md file, and a Skill in Antigravity? A Rule is persistent context loaded at the prompt level (coding standards, stack details). A Workflow is a structured sequence of steps for a repeatable task (deployments, PR responses). An agent.md file defines a named custom agent with its own model, permissions, and MCP access. A Skill (SKILL.md) is a capability the agent discovers by description and reads in full only when relevant to the current task — Google’s docs call this progressive disclosure.

Q5. Where do workspace-level Rules live, and does the folder name matter? .agents/rules/ is the current default. Antigravity still reads .agent/rules/ (singular) for backward compatibility with projects set up before the folder was renamed.

Q6. Can Antigravity’s agent edit files outside my project folder? Not by default. Agent Non-Workspace File Access is off unless you explicitly enable it, and Google’s docs recommend leaving it off for exactly the security reason you’d expect — it expands what an errant command can reach beyond the current project.

Related Reading on The Prompt Shelf

• AGENTS.md vs CLAUDE.md vs GEMINI.md: The Complete 2026 Comparison
• Does Claude Code Support AGENTS.md? The Complete 2026 Reference
• Amp’s AGENTS.md Discovery: The System-Wide Paths (2026)
• 15 Best Claude Code Skills 2026
• AGENTS.md Not Loading? How to Debug It in 2026

Keep Sandboxed Subagent Credentials Out of the Repo

A commandExecutionPolicy: sandbox subagent is a good default — but a sandboxed process still needs real credentials for anything it legitimately calls out to, and pasting an API key into an agent.md file or a Skill’s resources/ folder defeats the sandbox before it starts. 1Password CLI’s op run injects secrets into the process environment at runtime instead, so your Rules, agent definitions, and Skills can describe what a subagent is allowed to touch without ever containing the keys themselves.