Type to search the docs and updates.

Browse documentation

Antigravity native reference

Start with the Antigravity setup.

Native mappings

Entry point

.agents/AGENTS.md is the documented per-directory entry point (<dir>/.agents/AGENTS.md or <dir>/.agents/GEMINI.md, both always_on and frontmatter-free). It stays apart from the root AGENTS.md that Codex, Amp, and Warp use.

Paths

Rules, skills, and MCP go to the plural .agents/ form Antigravity prefers (rules, skills). Antigravity lists the singular paths as legacy.

Plugins

Point any output folder or file key at .agents/plugins/<name>/ to ship those specs as a workspace plugin, active only in that project. agnostic-ai writes the required plugin.json at the plugin root, one per plugin, when an output key points at a component of the plugin layout: skills/, agents/, rules/, hooks.json, mcp_config.json, or mcp.json. A path inside a component, such as .agents/plugins/team/skills/extra, gets no manifest.

To bundle MCP servers in a plugin, set outputs.antigravity.mcp-file to .agents/plugins/<name>/mcp_config.json, the path in the plugin documentation. Sync also recognizes mcp.json for the manifest and notes the documented filename. The standalone file stays at .agents/mcp_config.json.

Sync keeps an existing plugin.json it did not write and prints a note. Manifests recorded by an earlier sync remain managed.

Rules

Every file starts with frontmatter declaring a trigger. Antigravity silently discards a file without one or with an unknown value. The generated-file header follows the closing ---.

  • alwaysApply is checked first, as in Devin Desktop / windsurf and Cursor. true writes trigger: always_on and ignores globs, so the rule that new rule creates (globs: "**/*" plus alwaysApply: true) stays always-on. When unset, it counts as false if globs holds something other than a catch-all such as **/*, and as true otherwise.
  • With alwaysApply: false (or globs and no alwaysApply), globs becomes trigger: glob plus a quoted, comma-joined globs. A description alone becomes trigger: model_decision. A rule with neither becomes trigger: manual (loads only on an @-mention). The Antigravity CLI does not support rule mentions, so a manual rule does not load there. Each case has the field it needs, so no sync note appears. description is kept on any trigger.
  • x-antigravity.trigger overrides the mapping. import antigravity writes it, because the portable fields cannot always recover the trigger. A manual rule with a description would come back as model_decision. An override missing its field (globs for glob, description for model_decision), or outside always_on/glob/model_decision/manual, becomes trigger: manual with a sync note, never always_on.
  • 24,000-byte cap. Antigravity truncates a rule file over 24,000 bytes after expanding @[label](path) includes. agnostic-ai writes it in full and adds a sync note, so split the rule. The count covers the written file (frontmatter, generated-file header, heading) and expands the built-in memory rule's project and checkout personal indexes, stripping included frontmatter. Other rules' includes are not counted.
  • 20,000-token budget. All always_on rules share 20,000 tokens. Past it, Antigravity replaces its largest rules with a path: description pointer. sync gives no note, so give large rules a description.
  • Scoped rules: scope: <dir> writes to <dir>/.agents/rules/<name>.md with the same frontmatter. Antigravity documents that it does not load rules from folders below the workspace. Use a workspace rooted at the scoped directory when relying on those rules.

Agents

One custom subagent at .agents/agents/<name>/agent.md, the nested form in Antigravity's subagent reference (a flat form also exists). Frontmatter has the required name and description. The body is the system prompt.

  • Goose and OpenHands scan only top-level .md files in that folder. The nested form keeps Antigravity's model tier apart from their model IDs. import antigravity reads flat files only when no nested profile exists, so it skips their agents.
  • Devin reads this folder too. With windsurf in targets, Devin finds this profile and .devin/agents/<name>.md under one name, and only the Devin copy has allowed-tools. See the shared agent discovery.
  • A portable tools list is dropped with a sync note. Antigravity has its own names (view_file, replace_file_content, grep_search, run_command, ...), and an unknown one can hang the subagent. Set x-antigravity.tools instead.
  • model is a tier (inherit, flash_lite, flash, pro), so any other value is dropped the same way. The plugin reference documents flash_lite, accepted by the released plugin parser. Set it through model or x-antigravity.model.
  • Other documented keys (mainAgent, subagent, commandExecutionPolicy, mcpServers, skills/plugins) go under x-antigravity.

Skills

Antigravity's native skills layout, shared with every tool that writes .agents/skills/ (see shared skills), so identical folders are written once. Frontmatter is cut to name and description. Files next to the skill are copied unchanged. sync --global writes ~/.gemini/config/skills/<name>/, the global path for the IDE and Antigravity app.

Antigravity documents no field that keeps a skill user-only: the agent reads relevant skills on its own, and /<skill-name> runs one by hand (Antigravity skills). Its disable-slash-command: true does the opposite, leaving the skill to the model. So disable-model-invocation is dropped with a note, and commands are skipped.

MCP

One mcpServers object in .agents/mcp_config.json (docs).

  • agnostic-ai writes remote servers with serverUrl. Antigravity also accepts url as an alias; httpUrl is unsupported. stdio servers have command, args, env, and cwd. Remote ones add headers.
  • Both kinds accept disabled by that name (see disabled support by target), unlike Codex and Kilo, which write enabled: false.
  • authProviderType, oauth, disabledTools, description, roots, and any new field go under x-antigravity, like Zed and Warp.

Hooks

Hooks are merged into .agents/hooks.json (or outputs.antigravity.hooks-file), the documented location.

  • Keyed by definition name, not event, unlike every other tool with hooks. Each spec becomes a top-level definition named after it, holding its one event. disabled: true writes enabled: false beside the event key, the reverse of MCP's literal disabled.
  • Six events: PreToolUse, PostToolUse, SessionStart, PreInvocation, PostInvocation, Stop. Other events are skipped with a sync note. The first two hold {matcher, hooks: [...]} groups. The other four hold a plain handler list and ignore the matcher, which gets a note. SessionStart runs once when a conversation starts, before the first model call. The portable on: session-start is not mapped; set event: SessionStart or x-antigravity: {event: SessionStart}.
  • Per handler: type (defaults to "command", and is always written), command, and optional timeout (seconds, vendor default 30).
  • A Claude-style matcher is valid regex that matches none of Antigravity's tool names. It is written as is with a sync note, as in OpenHands, Crush, and Windsurf.

hook run reads a successful Stop reply of {} as allow, matching the plugin guide and the agy 1.5.8 backend. A string decision: "continue" still reads as block. PreToolUse requires a decision.

Commands

The public-preview docs do not confirm them, so they are skipped with a warning. on-unsupported: silent suppresses it.

Leftovers from older versions
  • Older versions wrote the undocumented .agent/AGENTS.md. Sync renames a file it wrote there to .agent/AGENTS.md.bak.
  • Sync removes the .agent/rules and .agent/skills files it wrote, unless outputs.antigravity.rules-dir / skills-dir opts back into the legacy path.
  • Agents used to be flattened into .agents/rules/agent-<name>.md, which the subagent loader does not read. Sync removes the copy it wrote for every current agent.
  • Sync removes a flat agent profile it wrote when no enabled tool still writes it. With Goose or OpenHands enabled, it stays as their output.
  • The IDE still loads ~/.gemini/antigravity/skills/, which older versions wrote, but the Antigravity app does not. Move those skills or re-run sync --global.

Config keys

KeyDefaultNotes
outputs.antigravity.rules-dir.agents/rules
outputs.antigravity.agents-dir.agents/agents
outputs.antigravity.skills-dir.agents/skills
outputs.antigravity.mcp-file.agents/mcp_config.json
outputs.antigravity.hooks-file.agents/hooks.json
outputs.antigravity.rules-fileunsetwrites one legacy merged file and skips the instructions that point to source specs

Global configuration

agnostic-ai sync --global --only antigravity adds your home MCP specs to ~/.gemini/config/mcp_config.json, using the same fields as project output. A disabled server keeps disabled: true.

agnostic-ai import --global antigravity reads this file, maps serverUrl back to url, and keeps extra fields under x-antigravity. See global MCP ownership and name conflicts.

Import

agnostic-ai import antigravity reads .agents/rules, .agents/skills/ (with bundled files), and .agents/AGENTS.md. It falls back to .agent/rules, .agent/skills/, and .agent/AGENTS.md only when the preferred path is absent. It also looks for <dir>/.agents/rules/ copies to rebuild scoped rules.

  • Triggers: trigger becomes alwaysApply (always_on to true, glob/model_decision/manual to false). It is also kept under x-antigravity.trigger, which sync reads first, so a manual rule with a description stays manual. An unknown trigger gets no alwaysApply and a warning, and sync writes it as manual, never always_on.
  • Globs: globs is kept, and the singular glob: is merged into it.
  • Agents and MCP: nested profiles win over flat files. serverUrl becomes url, and other fields are kept under x-antigravity. An agent's tools, commandExecutionPolicy, mainAgent, subagent, mcpServers, skills and plugins move there too (an inline mcpServers entry that may hold a credential or cannot be read with confidence, such as a URL password, api_key query, header, env value, argument, unknown key or oauth secret, is left out with a warning, since Antigravity has no ${NAME} form for it), and sync writes them back; remove one from the agent file and the next import drops it. A spec imported before v0.95.0 can keep a stale top-level tools list; delete it, or delete the spec and import again.
  • Plugin files: import reads the configured outputs.antigravity.mcp-file, agents-dir, and rules-dir. These paths can point into .agents/plugins/<name>/. Import does not use skills-dir. Skills come from .agents/skills/, with .agent/skills/ as a fallback. Import skips everything else under .agents/plugins/.

Absolute MCP file paths must resolve inside the project and outside .git. Import previews use the same boundary through project links and Windows short paths; a source folder alias does not grant access to an outside MCP file.