Rules and Workflows in Antigravity: teaching AI to follow your processes

November 3, 2026

Updated:

Guide
Rules and Workflows in Antigravity: teaching AI to follow your processes

Rules in Antigravity are long-term instructions (code conventions, architectural constraints, prohibitions) that Google Antigravity finds on its own in the directory and feeds into the agent's context on every turn, instead of you having to repeat them in each command. Workflow is a sequence of steps written in Markdown, called with a "/" prefix. Most importantly, according to official documentation read on 03/11/2026: the old-style workflow stopped working on 19/10/2026 and Google recommends switching to skill. This post does not promise that rules make AI perfectly compliant; the model can still slip up, and we have not yet measured compliance. If you are unfamiliar with Antigravity, read What is Antigravity? first. The post goes through rules and skills, GEMINI.md and AGENTS.md, rule scope, activation modes, limits, converting workflows to skills, file search order, and how OPCAIOS uses them.

Diagram of rules and workflows in Antigravity: global rules and project rules merged into context, four activation modes always_on, model_decision, glob, manual; old workflow converted to skill using /migrate-workflows; file search order from workspace up to repo root
Rules are constraints that always travel with the agent; skills are multi-step procedures called when needed. Diagram: OPCAIOS.

How are rules in Antigravity different from skills?

Rules in Antigravity are constraints and invariants, while skills are multi-step procedures, according to /docs/rules (read 03/11/2026). The documentation gives an example: "always use zod to validate data" is a rule, while "how to run a database migration" is a skill. The difference lies in how they are loaded. Rules are self-discovered by Antigravity and fed into context by activation mode. Skills only get their name and description added to context; the agent reads the full instructions when the task matches the description. Rules also stack: Antigravity merges all rules it finds; one file does not replace another. A practical breakdown for solo workers:

  1. Things that must be right everywhere (response language, forbidden directories, naming conventions): write as a rule.
  2. Things needed only for one specific task (deploy, write a post, back up): write as a skill.

The concept of skill in general is covered in What is a skill.

Where do GEMINI.md and AGENTS.md go in a project?

GEMINI.md and AGENTS.md are two rule file names that Antigravity reads as plain Markdown, needing no frontmatter and always enabled. According to /docs/rules, in the workspace directory and each parent directory up to repo root, Antigravity loads rules from three locations:

  1. AGENTS.md or GEMINI.md right in that directory.
  2. .agents/AGENTS.md or .agents/GEMINI.md.
  3. Files in .agents/rules/*.md (also accepts the old .agent/rules/ directory).

Antigravity does not read rules in subdirectories below the workspace, even if the agent reads or edits files there. Since AGENTS.md is a convention shared across many agents, one file can serve both Antigravity and other tools; see What is AGENTS.md and What is CLAUDE.md to compare with Claude Code.

How are global rules different from project rules?

Global rules apply to every project on the machine, while project rules apply only to one workspace and should be committed to the repository so the team can use them together. According to /docs/rules (read 03/11/2026):

Type Location per docs Frontmatter
Global, single file ~/.gemini/AGENTS.md, ~/.gemini/GEMINI.md, ~/.gemini/config/AGENTS.md, ~/.gemini/config/GEMINI.md Not needed, always on
Global, module form ~/.gemini/config/rules/*.md Required
Per project AGENTS.md, GEMINI.md, .agents/rules/*.md from workspace up to repo root Required for files in rules/

There is a small difference between surfaces: the Antigravity IDE's list of global rules in the documentation only mentions ~/.gemini/AGENTS.md, ~/.gemini/GEMINI.md, and ~/.gemini/config/rules/*.md. In the app and IDE, create rules via Customizations panel, Rules tab, + Global or + Workspace button. Best to keep global rules very short.

Four Trigger Modes and How They Work

A trigger mode is the trigger key in the YAML frontmatter, which determines when a file in rules/ gets loaded into context. According to /docs/rules, there are four values:

  1. always_on: loads the entire content into the system prompt every turn. If you don't need frontmatter, put it straight in AGENTS.md.
  2. model_decision: loads only the path and description; the agent reads the full text when the description matches. Requires a description.
  3. glob: auto-activates when the agent works with files matching the pattern in globs, for example "*.ts, *.tsx".
  4. manual: never auto-loads, only added when you @-mention the rule name. Antigravity CLI does not support rule mentions.

A trap worth remembering: files in .agents/rules/ missing frontmatter, or with a trigger written wrong like alwaysOn or modelDecision, get skipped without error. Here's an example of a rule using the file pattern (hypothetical, for illustration):

---
trigger: glob
globs: "*.sql"
description: "Rules when writing database migrations."
---
# Migration
1. Never delete or rename columns in a single deploy.
2. Each migration must have a way to roll back.

Antigravity only scans .md files sitting directly in rules/; files in subfolders are skipped unless declared in .agents/rules.json.

How Does Antigravity Handle Long Rules?

Antigravity sets two limits so rules don't consume the entire context window, according to /docs/rules read on 03/11/2026. First, each rule file is capped at 24,000 bytes, counted after all included files are inserted; anything over gets cut. Second, all global rules and always_on rules share a budget of 20,000 tokens, separate from the budget for skills and MCPs. When the total exceeds 20,000 tokens, Antigravity automatically downgrades the largest files from full text to a single pointer line with path and description, so the agent reads them when needed. That's why a rule's description matters even for always-on rules: it's what remains when a rule gets downgraded. Rules also support two reference syntaxes. The @[label](path) syntax inserts the full content of the target file into the rule. The @filename syntax just converts to an absolute path in the workspace so the agent knows exactly which file. You should split long rules into multiple model_decision files.

What Is a Workflow in Antigravity and Why Switch to Skills?

A workflow in Antigravity is a Markdown file holding a title, description, and sequence of steps, called with the /workflow-name command, according to the page /docs/ide/workflows (read on 03/11/2026). A workflow can call another workflow, and each file is capped at 12,000 characters. However both the workflow page and the page /docs/migration/workflows-to-skills state: workflows are discontinued as of 19/10/2026, and Google will have a new workflow system with migration guidance afterward. After that date, the old workflow folder is no longer indexed or callable via slash command. We have not verified this behavior on a machine ourselves.

Criterion Old Workflow Skill
Standard Antigravity proprietary format Open Agent Skills standard
Structure One .md file Folder with SKILL.md and attachments
Project location .agents/workflows/<name>.md .agents/skills/<name>/SKILL.md
Global location ~/.gemini/config/workflows/<name>.md ~/.gemini/config/skills/<name>/SKILL.md
Load in context Entire file Name and description first, content on demand
Call with "/" Yes Yes, /<skill-name>

The /migrate-workflows command in the Antigravity app scans both workflow folders, creates corresponding skills, renames the source files to .bak suffix, and activates the new skills. If a workflow and skill share a name, the skill takes priority.

How does Antigravity search for rules and skills in order?

Antigravity searches for customizations in two scopes: workspace (the .agents/ directory along with AGENTS.md, GEMINI.md) and personal (~/.gemini/config/ along with ~/.gemini/AGENTS.md, ~/.gemini/GEMINI.md), according to /docs/customization-discovery (read on 03/11/2026). The main rules are:

  1. Check the workspace directory and each parent directory, stopping at the repo root (the directory containing .git); outside the repo, only the workspace is checked.
  2. Don't search into subdirectories below the workspace.
  3. Scan each customization directory at exactly one level: skills must be directly in skills/, rules directly in rules/; to go deeper, declare them in a manifest file like skills.json, rules.json.
  4. Skill name collision: personal directory within the repo (if repo configured) beats workspace, workspace beats ~/.gemini/config/, finally built-in skills.
  5. Rules don't override each other: all rules found are loaded.

Antigravity re-reads rules and skills before each turn, so new files take effect in the next message. In the CLI, run /skills reload to update the command list. Skills and MCP go deeper in MCP and skills in Antigravity.

OPCAIOS experience

Checked on 03/11/2026 on the main Mac (Antigravity 2.28.x app, IDE 2.5.x, CLI agy 1.4.12):

  1. The user-level GEMINI.md file has only one line: always reply in Vietnamese.
  2. The shared process lives in AGENTS.md, placed in the user home directory and in the Obsidian notes repo: read documents at session start, write logs at session end, sync via one shared state file.
  3. There is exactly one global workflow file but it's an empty template, undocumented, not actually used. So the 19/10/2026 milestone doesn't affect us.

Lessons from comparing the documentation: AGENTS.md in the user home directory is not on the global rules list, so it's only loaded when that directory is on the path from workspace up to the repo root. We haven't verified whether this file gets loaded across all projects.

Frequently Asked Questions

Should I use GEMINI.md or AGENTS.md in Antigravity?

According to the /docs/rules documentation, Antigravity reads both files with the same handling: plain Markdown, no frontmatter, always on, and content is cumulative. If you only use Antigravity, either name works. If you use multiple agents like Claude Code, Codex, Cursor, AGENTS.md is more convenient because it's a shared convention that many tools understand, so you only maintain one set of rules. Don't copy the same content into both files, because the cumulative rule mechanism will cost you double the tokens.

Why doesn't my rule have any effect?

Check in the order from /docs/customization-discovery. First, is the file in the right place: workspace or parent directory up to the repo root, not a subdirectory. Second, is the file directly in rules/, because subdirectories are skipped. Third, does the file in rules/ have a frontmatter with a valid trigger written in lowercase with underscores, like always_on. Fourth, is the rule downranked to a pointer because it exceeded the 20,000 token budget. Finally, remember that the model can still miss a rule.

Will my old workflow still run?

According to documentation read on 03/11/2026, old-style workflows stopped working from 19/10/2026; after this date the workflow directory is no longer indexed or called by slash commands. Google said there will be a new workflow system and migration guidance later. The current workaround is to run /migrate-workflows in the Antigravity application, or manually create a skill directory and move content into SKILL.md with name and description frontmatter. The original file is kept with a .bak extension.

Can skills be called with a slash like workflows?

Yes. According to the workflow-to-skills migration page, any skill in .agents/skills/<name>/ or ~/.gemini/config/skills/<name>/ can be called with /<name>, just like old workflows. The difference is that agents can also self-select skills when descriptions match, so the description must clearly say what the skill does and when to use it. In the CLI, to add a skill while running, type /skills reload or open a new conversation. Compare the different extension mechanisms in slash command, skill, plugin or MCP.

Can someone with no coding experience write rules themselves?

Yes, because rules are just Markdown files written in plain language. Start with a short AGENTS.md: response language, directories not to edit, tasks to do before deleting or deploying, how to report when done. After a few sessions, use the /learn command so Antigravity can suggest rules from the times you edited it, then review each suggestion. To learn how to teach AI agents to follow your own workflow, see the AI application training course from OPCAIOS.

Sources: Google Antigravity documentation at antigravity.google: /docs/rules, /docs/ide/workflows, /docs/migration/workflows-to-skills, /docs/skills, /docs/slash-commands, /docs/customization-discovery (read 03/11/2026); have not independently verified that old workflows stopped running after 19/10/2026, have not verified that AGENTS.md in the user's root directory is loaded in all projects, have not measured rule compliance. Experience is from OPCAIOS.

Translated from Vietnamese with AI. Read the original.

Want to apply this in your business?

Book a free 30-minute call (Vietnam time, in English or Vietnamese).

Book a call