Antigravity Skill Specification & SKILL.md Breakdown

Agent Architecture

1. The Antigravity Skill Model

Unlike traditional developer scripts that require human reading and manual parameter assembly, an Antigravity Skill is a self-contained capability package designed primarily for consumption by an autonomous AI agent (such as Antigravity / Gemini).

A skill package packages three complementary layers together:

Layer	File / Location	Audience & Function
1. Discovery Frontmatter	`SKILL.md` (lines 1–8)	System Prompt Injector: Provides a concise description that the model evaluates against human prompts to determine if the skill is needed.
2. Agent Runbook	`SKILL.md` (lines 10–132)	AI Agent Playbook: Teaches the agent exact prerequisites, execution flags, sandbox bypass rules, recipe commands, and output schemas.
3. Companion Executable	`scripts/agy-brain-explorer.py`	Execution Engine: The standalone Python CLI script with inline PEP 723 metadata that performs the filesystem traversal, parsing, and Markdown rendering.

ℹ️

Skill Package Philosophy: Scripts do the heavy computational lifting (parsing large JSONL files, regex scanning, computing timestamps), while SKILL.md provides the decision tree and instructions so the LLM invokes the script accurately without hallucinations.

Context Efficiency

2. Progressive Disclosure & Agent Lifecycle

Loading every skill's full markdown documentation into the AI model's context window on every turn would waste tens of thousands of tokens and slow down inference. Antigravity uses Progressive Disclosure:

1

Skill Indexing

Antigravity scans .agents/skills/ and ~/.gemini/config/skills/. It extracts only the name and description from the YAML frontmatter.

2

Prompt Matching

When a user prompts (e.g., "Show me tool calls from yesterday's session"), the model compares user intent against the skill's summary.

3

Runbook Loading

The agent calls view_file on SKILL.md to read the complete runbook instructions into active context.

4

Execution

The agent runs agy-brain-explorer.py via run_command with BypassSandbox: true and presents the Markdown output.

User Prompt Intent	Trigger Matches?	Agent Action
"What did we do in our last Antigravity session?"	YES	Loads `SKILL.md` → runs `uv run ... --limit 1` → summarizes trajectory.
"Audit shell commands run during session 74126ecc"	YES	Loads `SKILL.md` → runs `uv run ... 74126ecc commands` → reports shell commands table.
"Please refactor the database connection in db.py"	NO	Skill remains unread; 0 context tokens consumed.

Frontmatter Anatomy

3. YAML Frontmatter Specification

The top of SKILL.md contains the YAML frontmatter block delimited by --- lines. This is the only portion loaded into the agent's baseline system prompt:

SKILL.md (Lines 1–8)

---
name: agy-brain-explorer
description: >-
  Discover, list, inspect, and audit Google Antigravity session trajectories,
  transcripts, tool invocations, and execution steps across all brain storage
  directories under ~/.gemini. Use whenever asked to list recent/past sessions,
  review session histories, inspect tool executions, or debug trajectory steps.
---

Field	Syntax & Type	Operational Mechanism
`name`	String (slug)	Unique identifier for the skill (`agy-brain-explorer`). Appears in Antigravity's internal tool registry and available skills catalog.
`description`	Folded block string (`>-`)	Specifies both capability scope (what it does) and trigger conditions (when to use it). The phrasing "Use whenever asked to..." acts as an explicit activation heuristic for the LLM.

Zero-Config Python

4. Execution Runtime & UV

Antigravity skill runbooks require scripts to execute reliably without prerequisites like activating a .venv or running manual pip install steps. SKILL.md mandates the use of Astral's uv:

SKILL.md (Lines 16–27)

# From workspace root:
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py [OPTIONS] [COMMAND]

# Or from within the skill folder:
uv run scripts/agy-brain-explorer.py [OPTIONS] [COMMAND]

Behind the scenes, agy-brain-explorer.py defines standard PEP 723 inline script metadata:

scripts/agy-brain-explorer.py (Lines 1–6)

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "typer>=0.12.0",
# ]
# ///

When uv run executes, it inspects these comment lines, provisions an ephemeral, cached virtual environment in milliseconds, installs typer, and runs the script in complete isolation.

Security & Sandboxing

5. Sandbox Bypass Justification

One of the most critical instructions in SKILL.md is the explicit mandate for BypassSandbox: true:

⚠️

Crucial Execution Directive:

"Always set BypassSandbox: true when executing run_command." Without this parameter, execution fails deterministically for two foundational security reasons:

Failure Point	Standard Sandbox Behavior	With `BypassSandbox: true`
1. Subprocess Spawning (`uv run`)	The sandbox restricts process creation permissions. Invoking `uv run` fails immediately with: `Operation not permitted (os error 1)`.	Allowed to spawn child processes, construct cached Python virtualenvs, and execute the Typer CLI.
2. Out-of-Workspace Filesystem Access	Standard sandbox confines file reads strictly to the current workspace root directory.	Permits read access to Antigravity's global session stores located in `~/.gemini/antigravity/brain/`, `~/.gemini/antigravity-cli/brain/`, etc.

UI Integration

6. Native Markdown & Deeplinks

Traditional CLI tools emit ANSI escape codes (e.g. terminal colors, progress spinners) which degrade into garbled escape characters when returned to an LLM context.

SKILL.md establishes a Markdown-First Output Contract:

The script detects when run without a TTY or in agent mode and emits clean, GitHub-Flavored Markdown tables, blockquotes, and fenced code blocks.
Session identifiers are formatted with custom conversation:// URI deeplinks:

Deeplink Markdown Format

`74126ecc` [↗](conversation://74126ecc-9639-4ff3-9dcb-7ac2d9400986)

✔️

Interactive Chat Deeplinks: Because Antigravity's Chat UI registers the conversation:// URI protocol, clicking the [↗] link instantly navigates the developer's IDE directly to that past conversation history in the editor!

Annotated Code

7. Complete Annotated SKILL.md Breakdown

Below is the complete, line-by-line breakdown of the actual SKILL.md file from the repository, divided into its logical operational sections:

Part 1: Skill Discovery & Trigger Metadata

Lines 1–8 of SKILL.md

SKILL.md

---
name: agy-brain-explorer
description: >-
  Discover, list, inspect, and audit Google Antigravity session trajectories,
  transcripts, tool invocations, and execution steps across all brain storage
  directories under ~/.gemini. Use whenever asked to list recent/past sessions,
  review session histories, inspect tool executions, or debug trajectory steps.
---

Agent Behavior: This YAML block provides the metadata evaluated by the LLM during intent classification. The explicit phrasing specifies all trigger scenarios (listing, inspecting, auditing tool calls, debugging trajectory steps).

Part 2: Execution Environment & Sandbox Directives

Lines 10–39 of SKILL.md

SKILL.md

# Antigravity Brain Explorer Skill

This skill provides procedures and commands to discover, inspect, and audit Antigravity session trajectories and conversation logs using the helper script [`agy-brain-explorer.py`](scripts/agy-brain-explorer.py).

## Execution Environment & Prerequisites

### 1. Always Run via `uv`
Run Python scripts using [`uv`](https://docs.astral.sh/uv/) so PEP 723 inline script dependencies (`typer>=0.12.0`) are automatically resolved and cached without manual virtual environment management.

From the workspace root:
```bash
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py [OPTIONS] [COMMAND]
```

Or from the skill folder:
```bash
uv run scripts/agy-brain-explorer.py [OPTIONS] [COMMAND]
```

### 2. Mandatory Bypass Sandbox (`BypassSandbox: true`)
> [!IMPORTANT]
> **Always set `BypassSandbox: true` when executing `run_command`.**
> 1. Running `uv run` inside Antigravity's standard sandbox fails with `Operation not permitted (os error 1)` when attempting to spawn the Python process.
> 2. Discovering and inspecting session trajectories requires reading directory structures and JSONL transcripts located in user storage at `~/.gemini/**/brain/`, which reside outside the workspace sandbox boundary.

### 3. Native Markdown Rendering
> [!TIP]
> **All results render directly as GitHub Flavored Markdown.**
> Session IDs are formatted with copyable code plus Antigravity UI navigation links (`` `<short_id>` [↗](conversation://<full_session_uuid>) ``) so the user can easily copy the session ID to ask follow-up questions or click directly into past conversations from chat.

Agent Behavior: Instructs the agent on how to call run_command correctly. It explicitly warns against attempting to invoke without BypassSandbox: true, preventing runtime failure loops.

Part 3: Discovery & Search Workflows

Lines 42–75 of SKILL.md

SKILL.md

## Workflows & Command Reference

### 1. Discover and List Recent Sessions

Scan all brain directories under `~/.gemini` and display conversation traces ordered chronologically (newest first):

```bash
# List most recent 10 sessions formatted as Markdown with clickable conversation links (default)
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py --limit 10

# Filter by a specific brain root (e.g., 'antigravity-cli' or 'antigravity')
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py --brain antigravity --limit 10

# Filter sessions by initial user prompt query
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py -q "Please build a unified static HTML"
```

### 2. Search Sessions by Prompt or Deep Transcript (`search`)

Find sessions matching a prompt keyword or search across conversation turns and tool calls:

```bash
# Search sessions by initial prompt across all brain directories
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py search "Please build a unified static HTML"

# Filter search by brain root
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py search "build static docs" --brain antigravity-cli

# Deep search across all conversation steps (user requests, model responses, tool args, commands)
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py search "build-docs-site.js" --all-steps

# Search within a single specific session
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION> search "node --test"
```

Agent Behavior: Equips the agent to quickly find past work when a user asks "What did we discuss about X?" or "Find the session where we debugged the build script". The agent can use -q or search --all-steps to locate the session in seconds.

Part 4: Session Inspection, Auditing & Raw JSON

Lines 77–132 of SKILL.md

SKILL.md

### 3. Inspect Session Overview (`summary`)

Pass a session UUID, partial prefix (e.g. `c1e9ba23`), or directory path to view metadata, timing, duration, model, workspace, and tool usage frequencies:

```bash
# Markdown formatted overview (default)
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION_ID_OR_PREFIX>
```

### 4. Browse Conversation Timeline (`steps`)

Display conversation turns with step numbers, timestamps, sources (`USER_EXPLICIT`, `MODEL`), types, and preview/actions:

```bash
# Markdown table of conversation steps (default)
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION> steps --limit 20

# Filter to steps that called tools
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION> steps --tools-only

# Filter to user prompt steps only
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION> steps --user-only
```

### 5. Drill Down into a Specific Step (`step`)

Inspect the user prompt, model thinking, exact tool call parameters, triggering action, and step output logs:

```bash
# View step 5 details formatted in Markdown
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION> step 5

# Limit step output log preview to 100 lines
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION> step 5 --lines 100
```

### 6. Audit Tool & Command Executions

Quickly review all tool invocations or shell commands run during a session:

```bash
# List all tool invocations with targets and parameters in Markdown
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION> tools

# Audit all shell commands run via run_command with working directories in Markdown
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION> commands
```

### 7. Inspect Raw JSON Records (`raw`)

Retrieve untruncated JSON step data from `transcript_full.jsonl`:

```bash
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION> raw 1 --full
```

### 8. Compare Two Sessions Side-by-Side (`compare`)

Compare two sessions side-by-side to review timing, duration, step counts, user turns, tool invocations, files written, and outcomes:

```bash
# Compare two sessions by IDs or prefixes
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py compare <SESSION_1> <SESSION_2>

# Or via session inspection syntax
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION_1> compare <SESSION_2>
```

### 9. Inspect On-Disk Paths and Transcripts (`paths`)

Display exact disk locations and clickable file links (`file://`) for session directories, transcripts (`transcript.jsonl`, `transcript_full.jsonl`), logs, step outputs, and scratch files:

```bash
# Show disk paths for a single session
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION> paths

# Show disk paths for multiple sessions simultaneously
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py paths <SESSION_1> <SESSION_2>
```

Agent Behavior: Provides fine-grained diagnostic commands. An agent can compare two differing sessions side-by-side to diagnose regressions, audit executed shell commands with uv run ... <SESSION> commands, or instantly locate raw transcripts and artifact folders on disk with paths.

Interactive Tool

8. Interactive Workflow Explorer

Select any of the 9 skill workflows below to inspect how the agent translates human prompts into specific CLI invocations, tool parameters, and Markdown outputs:

Workflow 1: Discover & List Recent Sessions

Discovers conversation trajectories across all brain storage roots in ~/.gemini ordered chronologically.

Default Invocation

Agent CLI Command

uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py --limit 10

Agent run_command Tool Payload

{
  "CommandLine": "uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py --limit 10",
  "Cwd": "/Users/developer/my-project",
  "BypassSandbox": true,
  "WaitMsBeforeAsync": 5000,
  "toolAction": "Discovering sessions",
  "toolSummary": "List recent sessions"
}

Markdown Output Received by Agent

### Discovered 10 Antigravity Sessions

| Index | Session ID | Created At | Duration | Model | Initial Prompt |
| :---: | :--- | :--- | :---: | :--- | :--- |
| 1 | `74126ecc` [↗](conversation://74126ecc-9639-4ff3-9dcb-7ac2d9400986) | 2026-09-14 10:15 | 12m 40s | Gemini 2.5 Flash | Please build an HTML walkthrough... |
| 2 | `a901ff2e` [↗](conversation://a901ff2e-1102-4ab1-8933-4f2801e021a8) | 2026-09-13 18:22 | 4m 12s | Gemini 2.5 Pro | Fix the layout bugs in sidebar... |

The Antigravity Skill Contract & SKILL.md

1. The Antigravity Skill Model

2. Progressive Disclosure & Agent Lifecycle

3. YAML Frontmatter Specification

4. Execution Runtime & UV

5. Sandbox Bypass Justification

6. Native Markdown & Deeplinks

7. Complete Annotated SKILL.md Breakdown

8. Interactive Workflow Explorer

Workflow 1: Discover & List Recent Sessions