Antigravity Rules Tutorial: Set Up Rules & Workflows (2026)
Rules tell your Antigravity agent how to behave in every chat; workflows save multi-step routines you rerun with a slash command. This walkthrough follows a clean screen recording step by step — every screenshot verified, every step linked to the exact moment in the source video.
Quick answer — what Antigravity rules are
- Rules are persistent instructions Antigravity loads into the agent's context on every turn — coding standards, constraints, style. Workflows are saved checklists the agent runs on demand when you type a slash command.
- Create both from the Agent panel: open the Customization menu, then the Rules tab, and click + Global for all projects or + Workspace for the current one only.
- A + Global rule writes to ~/.gemini/GEMINI.md (AGENTS.md works too); workspace rules live in .agents/rules/*.md inside your repo. Frontmatter triggers decide when each modular rule loads: always_on, model_decision, glob or manual.
- Mind the budgets: one rule file is capped at 24 KB, and the ~20,000-token budget for inline global and always_on rules demotes the largest files to path pointers instead of truncating them blindly.
How To Use Google Antigravity Rules & Workflows [2026 GUIDE]
Video:Nexustech4:04
Rules — Google Antigravity documentation
Official docs:Google
Facts in this guide follow Google's official rules documentation wherever it goes beyond the video — including the 24 KB per-file cap, the 20,000-token inline budget and the four frontmatter triggers.
Screenshots are stills from the credited YouTube recording, used with attribution; each image deep-links to the exact second it was taken from. The written steps are our own.
Set up Antigravity rules and workflows, step by step
1 · Open the Customizations panel
- 1
Open Antigravity and confirm which project you are in
Launch Antigravity and look at the workspace name in the Explorer before doing anything else. Scope matters: a rule only follows you across projects if it is global, while workspace rules apply to the open project alone — so decide the scope before you write anything.
Antigravity IDE before any customization — note the workspace name before choosing a scope.Watch at 0:20 - 2
Open the Customization menu in the Agent panel header
In the Agent side panel, hover the icons at the top right until the tooltip reads Customization and MCP Servers, then click it. This opens the Customizations panel — the single place where rules and workflows live in Antigravity 2.x.
The Customization icon sits in the Agent panel header, next to MCP Servers.Watch at 1:30 - 3
Open the Rules tab
The Customizations panel opens on the Rules tab with two buttons: + Global and + Workspace. Below them Antigravity explains that rules help guide the behavior of the Agent. Pick + Global for instructions that should hold in every project, + Workspace to keep them repo-local.
An empty rules list with the + Global and + Workspace buttons.Watch at 1:38
2 · Create your first rule
- 4
Click + Global — Antigravity opens GEMINI.md for you
Clicking + Global opens the global rules file in the editor with a placeholder line. Hover it and the Global Antigravity IDE Rules File card appears: global rules are loaded into Agent mode across all your workspaces as specific guidelines. The card even lists four example rules you can borrow.
The hover card on the global rules file explains its scope and shows example rules.Watch at 1:53 - 5
Write your rules — short lines, one instruction each
Replace the placeholder with plain instructions, one per line: My testing framework is php8, Don't use these APIs: ..., Before making changes, create these plans first. Keep each rule a single clear sentence — vague paragraphs get ignored.
Rules are plain text, one instruction per line, no markup required.Watch at 2:12 - 6
Save the file — the rules are now active
Save GEMINI.md (the dot in the tab shows unsaved changes). Once saved, these lines are injected into the agent's context on every turn in every workspace, so you stop repeating the same instructions in chat. The info icon next to the editor re-opens the scope explainer at any time.
Three rules saved in GEMINI.md — active in every workspace from now on.Watch at 2:27
3 · Save a repeatable workflow
- 7
Switch to the Workflows tab
Next to Rules sits the Workflows tab. Antigravity describes workflows as saved prompts that Agent can follow — you trigger one by typing / in the Agent box. Use them for routines you repeat: reviewing a project, analyzing files, preparing a release.
The Workflows tab explains how a slash command triggers a saved routine.Watch at 2:58 - 8
Create the workflow and give it a name
Click + Global or + Workspace under Workflows and a name dialog appears with the example debug-memory-leak. Press Enter to confirm or Escape to cancel. The name becomes the slash command, so keep it short and descriptive — review-project beats workflow1.
Naming the workflow — this name turns into its slash command.Watch at 3:20 - 9
Hit the invalid-name error? Lowercase and hyphens only
Type a name with spaces or capitals and Antigravity rejects it: Invalid workflow name. Only lowercase letters, numbers, and hyphens are allowed. Rename with hyphens instead of spaces — read-the-main-files — and the dialog accepts it.
The validation error that appears when a workflow name contains spaces.Watch at 3:25 - 10
Describe the workflow in its frontmatter
Antigravity opens the workflow as a Markdown file (untitled.md until it is named) with a description field in the frontmatter. Write one line on when to use it — the agent reads this to decide whether the workflow fits the current request.
Every workflow is a Markdown file with description frontmatter.Watch at 3:36
4 · Write steps and run the workflow
- 11
List the steps in the order the agent should run them
Below the frontmatter, write numbered steps in plain text: read the main files, find anything that looks wrong, explain the problem in simple terms, suggest a fix, wait for approval before changing anything. An ordered checklist keeps the agent structured instead of guessing.
The first step, read the main files, typed under the frontmatter.Watch at 3:48 - 12
Save it, then run the workflow with a slash command
Save the workflow file, go back to the Agent box and type / to list your workflows — pick yours and the agent walks through the saved steps. Rules keep the agent's behavior consistent; workflows put your repeatable routines one keystroke away.
The finished workflow, ready to trigger with its slash command.Watch at 3:57
Antigravity rules not working? Check these first
Rules are not taking effect
Check the file location first: global rules must live under ~/.gemini/ (GEMINI.md or AGENTS.md, or modular files in ~/.gemini/config/rules/), and workspace rules in .agents/rules/ at the right directory level — only the immediate .md children of a rules folder are scanned, deeper files need registering in .agents/rules.json. Also check the frontmatter: triggers like alwaysOn (camelCase) are rejected, use snake_case always_on — and a manual rule only loads when you @-mention it in chat.
A rule file is being truncated
A single rule file larger than 24 KB is truncated after includes are expanded, so anything past the cap never reaches the model. Split oversized rules into smaller modular files inside a rules/ folder, and keep each file on one topic.
Rules silently missing from context
All inline global and always_on rules share a ~20,000-token budget. When the budget is exceeded, Antigravity demotes the largest rule files to one-line path pointers the agent reads on demand — the rule still exists but is no longer inlined. Trim or split your always-on set, or switch rarely used rules to model_decision or manual triggers.