The Antigravity IDE Mastery Guide: How I Use Google's Agent-First IDE Better Than 90% of Users

Most developers using Google Antigravity are running at maybe 10% of what the thing can actually do.

I know this because I was one of them. When I first downloaded Antigravity, I treated it like VS Code with a chat window bolted on. Ask a question, get an answer, copy-paste the code. Repeat until something works.

That's not how this tool was designed to be used.

After months of deliberate configuration, trial and error, and building what I now call my Agent Constitution, I've turned Antigravity into something fundamentally different. A semi-autonomous engineering partner that knows my codebase, follows my standards, and handles multi-step tasks while I focus on architecture.

This guide documents everything I've learned. It's not a beginner tutorial. It's a reference manual for developers who want to extract maximum value from the most powerful AI coding environment currently available.

---

#What Separates Power Users from Everyone Else

The difference between casual Antigravity users and power users comes down to configuration depth.

Power users don't rely on defaults. They build layered rule systems that shape agent behavior at global, workspace, and project levels. They encode their workflows into reusable skills instead of saying the same thing every conversation. And they treat Knowledge Items and Context Maps like they actually matter: structured external memory that sticks around between sessions.

By the end of this guide, you'll understand exactly how to build each of these systems.

---

#The Antigravity Architecture: Understanding the Foundation

Before getting into configuration, you need to understand where Antigravity stores its brain.

>The ~/.gemini/ Directory

Everything lives in ~/.gemini/. This is your control center. Here's the high-level structure:

~/.gemini/
├── GEMINI.md                 # The Constitution
├── global_rules/             # Modular rule imports
├── antigravity/
│   ├── brain/                # Conversation artifacts
│   ├── conversations/        # Session logs
│   ├── knowledge/            # Knowledge Items (KIs)
│   ├── skills/               # Skill library
│   ├── browser_recordings/   # Automation captures
│   └── mcp_config.json       # MCP server config
└── settings.json             # IDE preferences

GEMINI.md is the constitutional layer. That's the thing that matters. It's injected into every single conversation. The files in global_rules/ are imported by the constitution and define specialized protocols. The antigravity/ folder contains everything else: skills, knowledge, session data.

>The Three-Tier Hierarchy

Antigravity has three levels, and they don't mix:

Project rules can extend workspace rules, but nothing overrides global rules. That's intentional. The global constitution defines behaviors that must remain consistent regardless of context.

---

#The Modular GEMINI.md: Building Your Constitution

Here's my actual GEMINI.md file:

# GLOBAL AGENT CONSTITUTION (GEMINI.MD)

# Import Modules
@~/.gemini/global_rules/governance.md
@~/.gemini/global_rules/skills-protocol.md
@~/.gemini/global_rules/meta-skills.md
@~/.gemini/global_rules/context-map-protocol.md
@~/.gemini/global_rules/changelog-protocol.md
@~/.gemini/global_rules/rpe-workflow.md
@~/.gemini/global_rules/tools-reference.md
@~/.gemini/global_rules/context-hygiene.md

---

# ⚠️ IMMUTABLE SYSTEM PROMPT

**WARNING:** This `GEMINI.md` file defines the core operating logic
of the Agent. It **MUST NOT** be edited, altered, or ignored.
These are the Global Rules and must be followed at all times.

Notice how minimal this is. The constitution itself is just a loader. The actual logic lives in the imported modules. This design prevents context bloat and lets me update individual protocols without touching the core file.

>Why Modular Beats Monolithic

Early versions of my setup had everything in a single 2000-line GEMINI.md. It was a mess. The entire constitution got injected into every conversation, even when most of it wasn't even relevant. Updating one section risked breaking unrelated sections. And I couldn't easily share specific protocols across setups.

The modular approach solves all of that. Each module is a focused, single-purpose document. Updates are isolated. Modules can be copied between machines or shared with teammates.

---

#The Eight Global Rule Modules

Let me walk through each module and what it controls.

>1. governance.md - The Hierarchy Enforcer

This module tells the agent that ~/.gemini/GEMINI.md is the law. Here's the hierarchy:

• Global Rules apply to all projects and sessions. They're the agent's constitution.
• Workspace Rules live in ~/.agent/rules/. They provide nuances but can't override core behaviors.
• Enforcement is mandatory. These aren't suggestions.

This tells the agent explicitly that global rules are non-negotiable constraints.

>2. skills-protocol.md - Lazy Loading Mastery

All skills live in ~/.gemini/antigravity/skills/. The protocol defines how to use them:

1. Discovery - Scan skill descriptions in the global skills folder
2. Activation - Load skills lazily. Only inject the full SKILL.md when a match is found
3. Execution - Follow the specific steps in the SKILL.md exactly
4. Mandatory Check - Before any specialized task, check if a relevant skill exists

This matters because your context window isn't infinite. I've got 92 skills. Loading all of them into every conversation would be insane. Instead, the agent scans skill descriptions (which are short) and only loads the full instructions when relevant.

>3. meta-skills.md - Mandatory Automation

Meta skills are the core orchestration layer. They aren't optional:

When I submit a complex request, the agent is required to activate the RPE workflow. When I ask it to review completed work, it must use the review skill. So every conversation plays by the same rules.

>4. context-map-protocol.md - Persistent Memory

The Context Map is the agent's persistent memory for a project. It stores the project structure, key files, and architecture notes that carry across sessions. The agent checks these locations in order:

1. docs/CONTEXT-MAP.md
2. .context/CONTEXT-MAP.md
3. CONTEXT-MAP.md (project root)

The session protocol defines when to act:

Every project I work on has a CONTEXT-MAP.md. When I start a new conversation, the agent reads this file first.

>5. changelog-protocol.md - Historical Integrity

The Changelog is the historical record of work. The operational rules are:

1. Trigger - When the user issues a "Commit" command
2. Sequence - First update CHANGELOG.md with a concise summary, then proceed with the commit
3. Format - Entries must be dated and describe "What" and "Why"

Before any commit, the agent must update the changelog. This creates an automatic audit trail of all work.

>6. rpe-workflow.md - Research, Planning, Execution

This is the most important protocol in my entire setup. The agent must never execute a complex request blindly. It follows the Research, Planning, Execution loop:

1. Research - Gather context, read files, check docs
   • Priority: Web search FIRST, Knowledge Items SECOND
   • Mandatory: Use web search for ANY version-dependent info
2. Plan - Document specific steps in the task file
3. Execute - Perform the work

The key insight is web search priority. My internal Knowledge Items contain patterns from past work, but they can become outdated. The web has the latest truth. So the agent checks what's current before falling back on old knowledge.

>7. tools-reference.md - Available Capabilities

This module documents every tool the agent can use:

File Operations

Search and Discovery

Terminal and Commands

Browser Automation

Without this, the agent might not know it can automate browser interactions or run background commands.

>8. context-hygiene.md - Maintenance Protocols

Over time, the Antigravity data directory accumulates cruft. This protocol defines retention policies:

For Knowledge Items specifically:

• Merge overlapping KIs
• Archive project-specific KIs when projects retire
• Delete KIs with broken references

This keeps the system lean and high-signal.

---

#The Skills System: 92 Specialized Capabilities

Skills are what make Antigravity actually useful instead of generic.

>Skill Anatomy

Every skill follows this structure:

skill-name/
├── SKILL.md              # Required: Instructions
├── scripts/              # Optional: Executable code
├── references/           # Optional: Documentation
└── assets/               # Optional: Templates, files

The SKILL.md has two parts:

1. Frontmatter (YAML): Defines name and description. This is what the agent scans to decide if the skill is relevant.
2. Body (Markdown): The actual instructions. Only loaded after the skill triggers.

>Progressive Disclosure

Skills use a three-level loading system:

1. Level 1 - Metadata: Always in context (~100 words per skill)
2. Level 2 - SKILL.md body: Loaded when skill triggers (under 5k words)
3. Level 3 - References/Scripts: Loaded as needed (unlimited)

This means my 92 skills don't all load into every conversation. The agent sees a summary of each skill (name + description), and only loads the full instructions when relevant.

>Building Custom Skills

Here's a simplified version of my next-js skill:

---
name: next-js
description: Scaffolds and develops Next.js applications using App Router,
  React Server Components, and Cache Components. Use when creating a new
  Next.js project, implementing App Router patterns, or working with
  server-side rendering.
metadata:
  tags: frontend, next, react, ssr, app-router
---

# Next.js Skill

## When to Use
- User requests a new Next.js project
- Working with App Router patterns
- Implementing Server Components or SSR

## Standards
- Next.js 16+ with App Router by default
- TypeScript strict mode
- Tailwind CSS 4 for styling
- Server Components by default, 'use client' only when needed

## File Conventions
- `app/` for routes
- `components/` for reusable UI
- `lib/` for utilities
- `actions/` for server actions

## Component Pattern
\`\`\`tsx
// Server Component (default)
export default async function Page() {
  const data = await fetchData()
  return <div>{data}</div>
}
\`\`\`

## Verification
- Run `npm run build` to check for errors
- Verify pages render at expected routes

Notice the structure: When to Use (triggers), Standards (conventions), File Conventions (structure), Component Pattern (examples), Verification (confirmation steps).

>My Skill Categories

I organize my 92 skills into categories:

The number doesn't matter. What matters is that every skill in my library exists because I found myself repeating the same instructions across multiple conversations. If I'm saying it twice, it becomes a skill.

---

#Workspace Rules: Context-Aware Behavioral Constraints

Workspace rules live in .agent/rules/ and provide project-level governance without modifying global rules.

>The Four Trigger Modes

# 1. Always On - Applied to every interaction
---
trigger: always_on
---
[Rule content]

# 2. Manual - Only when explicitly called via @rule-name
---
trigger: manual
---
[Rule content]

# 3. Model Decision - Agent decides based on description
---
trigger: model_decision
description: When working on frontend components or UI design
---
[Rule content]

# 4. Glob Pattern - Applied to matching files
---
trigger: glob
globs: src/components/**/*.tsx
---
[Rule content]

>My Active Workspace Rules

Here are the rules I use on most projects:

no-mock-data.md

---
trigger: always_on
---

Do **NOT** use mock data, placeholder content, or dummy values.

**Prohibited:**
- Lorem ipsum or filler text
- Placeholder images (gray boxes)
- Hardcoded mock arrays
- "TODO", "TBD", "Coming soon" as content

**Required instead:**
- Real content and copy
- Use `generate_image` for actual images
- Connect to real APIs/databases

This rule exists because AI assistants love placeholder content. Left unconstrained, they'll fill your UI with lorem ipsum and gray boxes. This rule forces the agent to generate real content or explicitly ask for it.

rpe-workflow-mandatory.md

---
trigger: always_on
---

Use the **RPE (Research → Planning → Execution) workflow** for every task.

1. Create a task file in `~/.agent/tasks/`
2. Follow Research → Plan → Execute loop
3. Check off items as completed
4. Archive completed tasks

This enforces the RPE workflow at the project level, reinforcing the global rule.

browser-preview-mandatory.md

---
trigger: model_decision
description: When making frontend changes that affect visual rendering
---

After completing frontend changes, you MUST:
1. Open the browser to the relevant page
2. Capture a screenshot or recording
3. Include visual proof in the walkthrough

This ensures I get visual verification of UI changes, not just "I updated the component."

frontend-design-skills.md

---
trigger: model_decision
description: When working on frontend design, UI components, or UX improvements
---

When working on frontend or UI tasks, load and follow these skills:
- `frontend-design`
- `ui-ux-pro-max`
- `tailwind-design` (if Tailwind is in use)

This bundles related skills together. When the agent detects UI work, it automatically loads my design standards.

---

#Knowledge Items: Structured External Memory

Knowledge Items (KIs) are the memory that sticks around. Conversation history disappears. KIs don't. They carry across all sessions and all projects.

>KI Structure

Each KI lives in ~/.gemini/antigravity/knowledge/ and contains:

knowledge-item-name/
├── metadata.json         # Summary, timestamps, references
└── artifacts/
    ├── overview.md       # Entry point
    ├── standards/        # Core documentation
    └── implementation/   # Patterns and examples

>My Active Knowledge Items

>When to Use KIs vs Web Search

This is critical. KIs are snapshots from past sessions. They can become outdated.

Use web search for:

• Version numbers and current releases
• Library documentation and API changes
• Best practices that evolve over time
• Installation guides and dependencies

Use KIs for:

• Internal conventions and standards
• Project-specific patterns
• Company policies and business logic
• Verified patterns from past implementations

The rule is simple: web search first, KIs second. The web has the latest truth. KIs give you the project-specific stuff the web doesn't have.

---

#The RPE Workflow in Practice

The Research, Planning, Execution loop is the single most important behavioral pattern in my setup.

>How It Works

When I submit a complex request, the agent:

1. Creates a task file in ~/.agent/tasks/ with a timestamped name
2. Researches the requirements (web search, file exploration, KI consultation)
3. Plans the implementation with a checklist
4. Executes each checklist item, marking progress
5. Verifies the work
6. Archives the task file

>Example Task File

# Task: Implement User Authentication

## Objective
Add Supabase Auth to the Next.js application with email/password login.

---

## Checklist

### Research
- [x] Review Supabase Auth documentation
- [x] Check existing auth patterns in codebase
- [x] Evaluate session management options

### Planning
- [x] Document authentication flow
- [x] Identify required components

### Execution
- [x] Install Supabase SDK
- [x] Create auth context provider
- [/] Implement sign-in form  ← Currently executing
- [ ] Add protected route wrapper
- [ ] Write tests

### Verification
- [ ] Test login/logout flow
- [ ] Verify session persistence
- [ ] Check protected routes

The [/] notation indicates in-progress work. The task file serves as external memory. The agent can pick up exactly where it left off if the conversation gets interrupted.

---

#Advanced Patterns

>MCP Server Integration

Antigravity supports Model Context Protocol (MCP) servers for extended capabilities. My config includes:

• Firebase MCP: Direct Firestore and Auth integration
• Sequential Thinking: Enhanced reasoning for complex problems
• Cloud Run: GCP deployment automation

MCP servers are configured in ~/.gemini/antigravity/mcp_config.json.

>Browser Automation

The browser_subagent tool allows the agent to perform browser interactions autonomously:

• Navigate to URLs
• Click elements
• Fill forms
• Capture screenshots and recordings

I use this for:

• Visual verification of UI changes
• E2E testing without Playwright setup
• Documentation screenshots

>Context Window Optimization

The context window is a shared resource. Every token counts. My optimization strategies:

1. Modular rules: Only load what's needed per conversation
2. Progressive skill disclosure: Summaries first, full instructions only when triggered
3. Context hygiene: Regular cleanup of stale data
4. Concise KIs: Dense information, minimal fluff

---

#How to Build This

If you want to replicate this setup, here's the step-by-step:

>Step 1: Create the Modular Rule Structure

# Create the global rules directory
New-Item -Path "$HOME/.gemini/global_rules" -ItemType Directory -Force

# Create individual rule modules
@(
    "governance.md",
    "skills-protocol.md",
    "meta-skills.md",
    "context-map-protocol.md",
    "changelog-protocol.md",
    "rpe-workflow.md",
    "tools-reference.md",
    "context-hygiene.md"
) | ForEach-Object {
    New-Item -Path "$HOME/.gemini/global_rules/$_" -ItemType File -Force
}

>Step 2: Write Your Constitution

Create ~/.gemini/GEMINI.md:

# GLOBAL AGENT CONSTITUTION

# Import Modules
@~/.gemini/global_rules/governance.md
@~/.gemini/global_rules/skills-protocol.md
# ... add your modules

---

# ⚠️ IMMUTABLE SYSTEM PROMPT
These are the Global Rules. They must be followed at all times.

>Step 3: Create Your First Skills

Start with meta skills:

• rpe-workflow: Task management
• review: Quality assurance
• skill-creator: Building new skills

>Step 4: Set Up Workspace Rules

Create .agent/rules/ in your home directory or project root:

New-Item -Path ".agent/rules" -ItemType Directory -Force

Add your rules with appropriate triggers.

>Step 5: Initialize Knowledge Items

KIs are created automatically by the knowledge subagent, but you can seed important ones manually in ~/.gemini/antigravity/knowledge/.

---

#What Actually Changed

After building this system, my workflow is unrecognizable from where I started.

I used to type code while the AI suggested completions. Now I describe objectives. The agent researches, plans, and executes. I review artifacts and make strategic decisions. My time goes to architecture, code review, and decision-making. The stuff that actually requires a human brain.

This isn't about replacing developers. It's about offloading the mechanical execution so you can focus on the parts that matter.

---

#End of Transmission

I've spent hundreds of hours on this configuration. That sounds excessive until you realize the time compounds. Every rule I write applies to every future session. Every skill I build is available across every project. The investment pays for itself within weeks.

These patterns aren't theoretical. They're running in production across multiple projects, refined through daily use.

If you want to see the actual implementations, the skills, rules, and configurations are available in The Vault. The code is there. Explore at will.

---

Last updated: January 28, 2026