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

Most developers using Google Antigravity are operating at maybe 10% of the platform's actual capability.

I know this because I was one of them. When I first downloaded Antigravity, I treated it like a glorified VS Code with a fancy chat window. Ask a question, get an answer, copy-paste the code. Rinse and repeat.

That is 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 have transformed Antigravity into something fundamentally different: a semi-autonomous engineering partner that understands my codebase, follows my standards, and executes complex multi-step tasks while I focus on architecture and decision-making.

This guide documents everything I have learned. It is not a beginner tutorial. It is a systems 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 three things:

1. Configuration Architecture: Power users do not rely on defaults. They build layered rule systems that shape agent behavior at global, workspace, and project levels.

2. Skill Libraries: Instead of repeating the same instructions across conversations, power users encode their workflows into reusable skills that activate contextually.

3. Persistent Memory Systems: Power users treat Knowledge Items and Context Maps as first-class citizens: structured external memory that carries across sessions.

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

---

#The Antigravity Architecture: Understanding the Foundation

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

>The ~/.gemini/ Directory

Everything lives in ~/.gemini/. This is your control center. Here is 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

The key insight is that GEMINI.md functions as the constitutional layer-it is 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 operates on a strict governance hierarchy:

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

---

#The Modular GEMINI.md: Building Your Constitution

Here is 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 allows me to 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. This caused problems:

1. Context bloat: The entire constitution was injected into every conversation, even when most of it was irrelevant.
2. Maintenance nightmare: Updating one section risked breaking unrelated sections.
3. No reusability: I could not easily share specific protocols across setups.

The modular approach solves all three. 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 establishes that ~/.gemini/GEMINI.md constitutes the Global Rules for the environment. It defines the governance hierarchy:

• Global Rules apply to all projects and sessions. They function as the "Constitution" of the agent.
• Workspace Rules live in ~/.agent/rules/. They provide nuances but cannot override core behaviors.
• Enforcement is mandatory. These are operational requirements, not 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 is critical for context efficiency. I have 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 are not 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. This enforces consistency across all interactions.

>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 must operate via 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. This rule forces the agent to verify current best practices before relying on cached 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

Having this reference ensures the agent knows its full capability set. Without it, the agent might not realize 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 the modular extension system that transforms Antigravity from a general-purpose assistant into a domain expert.

>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 do not 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 is 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 key is not having 92 skills. The key is having skills that actually get used. Every skill in my library exists because I found myself repeating the same instructions across multiple conversations.

---

#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 will 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 persistent memory layer. Unlike conversation history (which is ephemeral), KIs 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 provide project-specific context that the web cannot.

---

#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 is 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 is 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

---

#Setting Up Your Professional Environment

If you want to replicate this setup, here is 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/.

---

#The Transformation

After building this system, my workflow changed fundamentally.

Before: I typed code. The AI suggested completions. I reviewed and edited.

After: I describe objectives. The agent researches, plans, and executes. I review artifacts and make strategic decisions.

The cognitive shift is profound. Instead of being a typist with an autocomplete, I operate as an engineering manager directing an autonomous contributor. My time goes to architecture, code review, and decision-making-the high-leverage activities.

This is not about replacing developers. It is about amplifying them. The agent handles the mechanical execution. I maintain creative and architectural control.

---

#End of Transmission

This guide represents hundreds of hours of configuration and iteration distilled into a single document.

The patterns here are not theoretical. They are production-tested across multiple projects, refined through daily use, and designed for developers who want to push the boundaries of AI-assisted development.

If you want to explore the implementations behind these patterns, the actual skills, rules, and configurations are available in The Vault. The code is there.

The system is open. Explore at will.

---

Last updated: January 28, 2026