Setting Up Google Antigravity: Rules, Skills and MCP

Setting Up Google Antigravity: Rules, Skills and MCP

Google Antigravity ships in three forms — a desktop app (Antigravity 2.0), a CLI, and IDE extensions — and all three read the same project-level configuration. That configuration is spread across a handful of standards this directory tracks everywhere: an AGENTS.md/GEMINI.md rules file, SKILL.md packs, custom subagents, MCP servers, lifecycle hooks and plugins. If you've set up Claude Code or Cursor before, the shape will feel familiar; the file paths and a few defaults are different, and this walkthrough sticks to what Antigravity's own docs document rather than guessing.

Google Antigravity Freemium

Google's agent-first platform: IDE, agent manager and the Antigravity CLI that replaced Gemini CLI

Freemium

🔥 US college students: 1 year of Google AI Pro free (higher limits)

8.0 Visit ↗

Installing the CLI

Antigravity publishes install scripts for macOS, Linux and Windows. The documented commands are:

# macOS / Linux
curl -fsSL https://antigravity.google/cli/install.sh | bash

# Windows PowerShell
irm https://antigravity.google/cli/install.ps1 | iex

The installer places an agy binary in a platform-specific directory (~/.local/bin/agy on macOS and Linux). Supported platforms are macOS 12 (Monterey) or later on Apple Silicon or Intel, Windows 10 64-bit or later on x64 or ARM64, and Linux x64/ARM64 with a reasonably current glibc. The desktop app and IDE extensions are separate downloads from antigravity.google/download if you'd rather work in a GUI than a terminal.

Once installed, the core loop is: create a project by pointing Antigravity at a local folder or a Git repository, then spawn an agent by typing a goal into the chat interface. You choose between Local mode, where the agent edits files directly, and New worktree mode, which runs the agent in an isolated Git worktree so you can review a diff before merging. If you've read our piece on git worktrees for parallel agents, this will look like the same idea built into the product rather than something you wire up yourself.

Rules: AGENTS.md and GEMINI.md

Antigravity treats AGENTS.md and GEMINI.md as interchangeable, frontmatter-free instruction files — see our AGENTS.md explainer for why that convention exists in the first place. You can drop either filename, or a .agents/rules/ directory, into any subdirectory of a project, and Antigravity discovers and applies them automatically:

• Workspace scope: AGENTS.md, GEMINI.md, or .agents/rules/*.md anywhere under the project root
• Global scope: ~/.gemini/AGENTS.md or ~/.gemini/config/AGENTS.md, applied across every project

Because these files carry no YAML frontmatter, their entire contents are kept "continuously active" in context — there's no conditional loading the way there is for skills. That makes them the right place for house style, testing conventions, or anything the agent should always know, and the wrong place for a large reference doc you only need occasionally (that's what skills are for).

Skills: packaging a workflow once

A skill is a folder with a SKILL.md file plus whatever scripts, examples or templates it needs:

my-skill/
├── SKILL.md       # required: instructions and metadata
├── scripts/       # optional: executable helpers
├── examples/      # optional: reference implementations
└── resources/     # optional: templates, schemas, data files

SKILL.md opens with YAML frontmatter:

---
name: code-review
description: Reviews code changes for bugs, style issues, and best practices. Use when reviewing pull requests or checking code quality.
---

# Code Review Skill

[Instructions follow here.]

The docs are specific about the description field: write it in the third person and include the keywords an agent would need to recognize when the skill applies, since that's the only thing the agent sees before deciding to load the full file — this is the progressive disclosure pattern Agent Skills were built around. Drop skill folders into <workspace-root>/.agents/skills/<skill-folder>/ for a single project, or into ~/.gemini/config/skills/<skill-folder>/ (Antigravity 2.0 and the IDE extensions) or ~/.gemini/antigravity-cli/skills/<skill-folder>/ (CLI) to make them available everywhere. Because this is the open SKILL.md format rather than an Antigravity-specific one, skills written for Antigravity are portable to any app that reads the same convention — browse what's already in the directory before writing your own. Archify is one example built for exactly this kind of cross-app portability:

Archify 🧩 SkillOpen source

Validated, interactive architecture, sequence and data-flow diagrams compiled from typed JSON

★ 76k · +4.5k this week

7.9 Visit ↗

Custom subagents

Where a skill is a reusable set of instructions the main agent follows itself, a subagent is a separate session with its own role, tools and model tier that the main agent can delegate to mid-task. Antigravity discovers subagent definitions at .agents/agents/<name>.md (or .agents/agents/<name>/agent.md) for a single project, and at ~/.gemini/config/agents/<name>.md globally. Each file is Markdown with YAML frontmatter:

---
name: security-auditor
description: Inspects source code for security vulnerabilities, memory leaks, and anti-patterns. Use before merging changes that touch auth, input parsing, or dependencies.
subagent: true
tools: [view_file, grep_search]
model: pro
commandExecutionPolicy: sandbox
---

You are an expert security auditor and code reviewer. Your primary
objective is to inspect source code for security vulnerabilities,
memory leaks, and anti-patterns.

Everything after the frontmatter becomes the subagent's system prompt. The subagent: true flag is what makes it invokable, tools scopes down what it can touch, model lets you assign a cheaper or more capable tier than the parent agent is using, and commandExecutionPolicy: sandbox keeps it from running arbitrary shell commands outside a sandbox. The parent agent calls invoke_subagent to spawn one of these as a concurrent session — useful for the same reason subagents are useful in Claude Code: a focused reviewer with a narrower toolset catches things a single long-running agent misses because it isn't juggling the whole task at once.

MCP servers

MCP configuration lives in a JSON file, either globally at ~/.gemini/config/mcp_config.json or per-workspace at .agents/mcp_config.json, both under a single mcpServers key:

{
  "mcpServers": {
    "local-server": {
      "command": "node",
      "args": ["/usr/local/bin/server.js"],
      "env": {
        "VARIABLE": "value"
      }
    },
    "remote-server": {
      "serverUrl": "https://api.example.com/mcp/",
      "headers": {
        "Authorization": "Bearer TOKEN"
      }
    }
  }
}

Each entry needs either a command (for a local, stdio-based server) or a serverUrl (for a remote one); everything else — args, env, cwd, headers, authProviderType, oauth, disabled, disabledTools — is optional and lets you scope what a given server can do. If you'd rather not hand-edit JSON, typing /mcp in the Antigravity CLI opens an interactive MCP Manager overlay for adding and toggling servers. For a deeper look at the authentication side of the serverUrl + headers/oauth pattern, see our remote MCP + OAuth explainer; for servers to actually add, the directory's MCP server list is sorted by category. Context7 for up-to-date library docs and Playwright MCP for browser automation are both common first additions; GitHub MCP Server covers issues, PRs and repo search if your workflow lives on GitHub.

Context7 🔌 MCP serverFreemium

Up-to-date, version-specific library documentation for your coding agent

★ 63k · +180 this week

9.0 GitHub ↗

Playwright MCP 🔌 MCP serverFree

Microsoft's MCP server for browser automation with Playwright

★ 38k · +196 this week

9.1 GitHub ↗

GitHub MCP Server 🔌 MCP serverFree

GitHub's official MCP server: issues, pull requests, code, Actions and security alerts

★ 33k · +132 this week

9.0 GitHub ↗

Hooks and plugins

Antigravity's lifecycle hooks fire at five points in an agent's run: PreToolUse and PostToolUse bracket every tool call, PreInvocation and PostInvocation bracket every model call, and Stop fires when execution ends. They're defined in a hooks.json — workspace-level at .agents/hooks.json, global at ~/.gemini/config/hooks.json, or bundled inside a plugin:

{
  "my-linter-hook": {
    "PostToolUse": [
      {
        "matcher": "run_command",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/lint.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

That example runs a lint script after every shell command the agent executes — the same pattern our hooks explainer covers for other apps, just with Antigravity's own matcher and event names.

Plugins are the distribution unit for all of the above: a single installable package that can bundle skills, subagents, MCP servers, hooks and linting rules together. Install one by dropping its folder into .agents/plugins/ (workspace) or ~/.gemini/config/plugins/ (global), by running /plugin for an interactive manager inside a session, or from the command line with agy plugin install <path>, agy plugin list, agy plugin enable <name> and agy plugin disable <name>. The desktop app also has a Marketplace under the Customizations tab for browsing plugins without touching the filesystem at all.

Putting the pieces together

Here's how the five mechanisms divide the work, side by side:

None of these are exclusive to Antigravity — AGENTS.md, SKILL.md and MCP are open conventions, which is why a skill or MCP server you set up here is likely to work unmodified in another agent that reads the same standard. The place to start is usually the smallest piece: one AGENTS.md with the two or three things you keep repeating to the agent, one MCP server for whatever external system you touch most, and skills only once you notice yourself writing the same multi-step instructions more than twice.

A reasonable first setup

For a typical project, a practical order to add things in:

1. Install the CLI or desktop app and open your repository as a project.
2. Write a short AGENTS.md at the project root — test commands, directory conventions, anything you don't want to repeat every session.
3. Add one MCP server that matches your stack: a docs server like Context7 if you're pulling in unfamiliar libraries, a browser server like Playwright MCP if the agent needs to verify UI changes, or your issue tracker's server if planning work starts there.
4. Turn your first repeated instruction into a skill once you notice yourself typing the same multi-step request twice — that's the signal it belongs in .agents/skills/ instead of your head.
5. Reach for a subagent only when a task genuinely benefits from a second, narrower-scoped pass — a security review before merging, for instance — rather than as a default.

Check the ecosystem page to see which skills, subagents and MCP servers in the directory already declare Antigravity support, and the deals page if you're comparing it against other app builders on price before committing.