Rules in Google Antigravity
Rules are standing instructions the agent follows in your project: code style, design rules, what not to touch. This page shows where rule files go, the four ways a rule can switch on, and the limits that make rules silently disappear.
Checked against the official Antigravity rules docs on 2026-10-14.
Where rule files go
| Scope | File | Note |
|---|---|---|
| This folder and below | AGENTS.md or GEMINI.md | Plain Markdown, no frontmatter. Always active for that folder. |
| This project, split into files | .agents/rules/*.md | Needs frontmatter with a trigger (see below). Old path .agent/rules/ still works. |
| All projects, one file | ~/.gemini/AGENTS.md or ~/.gemini/GEMINI.md | Also read from ~/.gemini/config/AGENTS.md and ~/.gemini/config/GEMINI.md. |
| All projects, split into files | ~/.gemini/config/rules/*.md | Needs frontmatter with a trigger. |
| CLI only | ~/.gemini/antigravity-cli/rules/*.md | Plus rules that come inside CLI plugins. |
Rules add up: folder rules, project rules and global rules all apply. When they disagree, the rule closer to the file wins. In the app and the IDE you can also create rules in Customizations with + Global or + Workspace.
The 4 triggers
trigger: always_onEvery turn: the whole rule goes into the prompt.
Also required: —
trigger: model_decisionThe agent sees only the description and reads the rule when the task matches.
Also required: description
trigger: globWhen the agent touches files that match the patterns.
Also required: globs
trigger: manualOnly when you @-mention the rule in chat.
Also required: —
Example: a UI rule that loads only for front-end files
Save as .agents/rules/ui.md. Our example; the format is the one in the docs.
---
trigger: glob
globs: "*.html, *.css, *.tsx"
description: "UI rules for this project's pages and components."
---
# UI rules
1. Use the colours and fonts in DESIGN.md; do not add new ones.
2. Every input has a visible <label>; no placeholder-only fields.
3. Buttons say what they do ("Save draft"), never "Submit".
4. Respect prefers-reduced-motion for any animation.To pull another file into a rule, write @[API Design Standards](../docs/api-standards.md): its contents are inlined. A plain @filename only points to the file.
Why a rule gets ignored
- No frontmatter, or a trigger written as
alwaysOn/modelDecision: the file inrules/is dropped. model_decisionwithoutdescription, orglobwithoutglobs.- The file sits in a subfolder of
.agents/rules/. Only files directly in that folder are read; subfolders must be listed in.agents/rules.json. - The file is over 24,000 bytes and the end was cut off, or always-on and global rules together are over 20,000 tokens.
FAQ
My rule in .agents/rules/ is ignored. Why?
Files in a rules/ folder must start with YAML frontmatter that has a valid trigger: always_on, model_decision, glob or manual (snake_case). The docs say a missing or unknown trigger (for example alwaysOn) makes Antigravity drop the rule without a warning. model_decision also needs a description, glob needs globs.
Do I need AGENTS.md or GEMINI.md?
Either works and both are read. They take no frontmatter and are always active for their folder, which makes them the simplest place for a few project rules. Use .agents/rules/ when you want rules that only load for certain files or tasks.
Is there a size limit?
Yes. A single rule file is cut off after 24,000 bytes. Global rules and always_on rules share a budget of 20,000 tokens; above that the largest files are turned into pointers the agent reads only when needed. Keep always_on rules short.
Rules, skills or MCP: which one do I need?
Rules are standing instructions ("always do X here"). A skill is a packaged way of doing a task, loaded when the task comes up. An MCP server adds tools the agent can call. Many setups use all three.
Next: install skills in Antigravity · add MCP servers · UI/UX skills
Source: antigravity.google/docs/rules