Antigravity Skills: Teach Gemini Agents Domain Expertise

Google rolled out Managed Agents in the Gemini API on May 19, 2026 at I/O. The Antigravity agent ID antigravity-preview-05-2026 is the same harness that powers the Antigravity IDE, exposed as a single REST call that spins up a Linux sandbox, runs the agent loop, and returns the result.

The part that is genuinely new and worth learning right now is how you shape that agent. The Antigravity team adopted a filesystem-native customization model: drop an AGENTS.md and one or more SKILL.md files into .agents/ inside the sandbox, and the runtime auto-discovers them. Same convention Anthropic uses for Claude Skills, same convention Cursor and Codex use for AGENTS.md. The pattern is converging across vendors, and Antigravity is the freshest implementation.

In this guide you wire up the official google-genai Python SDK, send your first interaction, layer a custom SKILL.md that teaches the agent how to produce a structured weekly digest, persist that configuration as a named managed agent with agents.create, then invoke it by ID. You will see the exact request payloads, the response shape, the cost behavior, and the gotchas that catch first-time users.

Prerequisites

• Python 3.10+ and a Gemini API key (free tier works for the preview, get one at aistudio.google.com/apikey).
• Compute is not billed during the Managed Agents preview. You still pay for Gemini 3.5 Flash tokens at $1.50 input / $9.00 output per 1M.
• pip install -U google-genai ≥ 1.5.0 (the version that ships the Interactions API).
• Familiarity with markdown frontmatter — Skills use the same --- YAML header convention as static-site generators.

Step 1: Understand the three customization layers

Antigravity stacks three layers on top of the base agent. Each is optional; you can use any combination. Learn the order before you write code, because it determines what overrides what.

Layer	Where it lives	What it does
system_instruction	Inline string in the request	Short persona / behavior tweak applied per call.
AGENTS.md	Mounted at .agents/AGENTS.md	Long-form persona, guardrails, house rules. Additive with system_instruction.
SKILL.md	Mounted at .agents/skills/<name>/SKILL.md	Named capability — auto-discovered, called on demand by the planner.

Mental model: system_instruction is for what you would normally jam into a prompt. AGENTS.md is a checked-in policy file that travels with the project. A skill is a reusable plugin the model can decide to invoke when the task fits its description.

Step 2: Set up the SDK

Install the Gen AI SDK and export your API key. The SDK reads GEMINI_API_KEY by default.

pip install -U google-genai
export GEMINI_API_KEY="your-aistudio-key"

Smoke-test with the base Antigravity agent first. This call provisions a fresh sandbox, runs the agent loop, and returns the final output text.

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Write a Python script that lists the first 20 primes, "
          "save it to primes.py, run it, and report the output.",
    environment="remote",
)

print("interaction:", interaction.id)
print("environment:", interaction.environment_id)
print("output:", interaction.output_text)

Expected console output (abridged, paths will differ between runs):

interaction: int_4a8e91c2b3
environment: env_7f2d1c9a04
output: I created primes.py with a Sieve of Eratosthenes implementation,
ran it, and the script printed:
2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67, 71
The file is saved in the sandbox at /workspace/primes.py.

Hold on to interaction.id and interaction.environment_id. The first one resumes the conversation; the second reuses the sandbox so files persist. They are independent — you can clear the chat but keep the files, or vice versa.

Step 3: Mount your first SKILL.md inline

A skill is a markdown file with YAML frontmatter at the top and instructions below. The frontmatter name and description are what the planner reads when deciding whether to use the skill. The body is what the model follows once it picks the skill up.

---
name: weekly-digest
description: |
  Use when the user asks for a weekly summary of activity from a folder
  of markdown notes. Produces a single digest.md file with a date-stamped
  header, three sections (highlights, decisions, follow-ups), and a links
  appendix.
---

# Weekly Digest Skill

When invoked:

1. Read every .md file under /workspace/notes/ that was modified in the
   last 7 days. Use `find /workspace/notes -name "*.md" -mtime -7`.
2. Group content under three headings: Highlights, Decisions, Follow-ups.
   Pull bullet items verbatim; do not paraphrase.
3. Collect every URL into a Links appendix at the bottom, deduplicated.
4. Write the result to /workspace/digest.md with a header
   `# Digest YYYY-MM-DD` (use today's UTC date).
5. Return the file path and a 3-line summary in the response.

Mount this skill at the right path and hand the agent a real task. The agent loop will plan, see the skill listed, decide it fits, and execute the steps.

skill_md = open("weekly_digest_skill.md").read()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Generate this week's digest from /workspace/notes.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/skills/weekly-digest/SKILL.md",
                "content": skill_md,
            },
            # Seed the sandbox with a few notes so the run produces something real.
            {
                "type": "inline",
                "target": "/workspace/notes/2026-05-26-standup.md",
                "content": (
                    "# Standup 2026-05-26\n"
                    "- Shipped v2 of the search index (Highlight)\n"
                    "- Decided to drop the legacy /v1 endpoint by July (Decision)\n"
                    "- Need to email enterprise customers about the cutover (Follow-up)\n"
                    "- Link: https://example.com/changelog/v2"
                ),
            },
            {
                "type": "inline",
                "target": "/workspace/notes/2026-05-27-review.md",
                "content": (
                    "# Review 2026-05-27\n"
                    "- Closed three RFCs on retrieval (Highlight)\n"
                    "- Will move evals to nightly cron (Decision)\n"
                    "- Link: https://example.com/rfc/047"
                ),
            },
        ],
    },
)

print(interaction.output_text)

Expected output:

Wrote /workspace/digest.md (118 lines). Summary:
- 5 highlights pulled from standup + review notes (May 26, May 27).
- 2 decisions captured verbatim, including the v1 sunset in July.
- 3 follow-ups, including the enterprise cutover email and an evals migration.

Two things are worth noticing here. First, you did not write tools=[...]: the Antigravity agent already has code_execution, google_search, and url_context by default, and filesystem access turns on automatically the moment you pass an environment. Second, the skill body is the contract — be specific about file paths, output format, and exit criteria. Vague skills get vague execution.

Step 4: Layer in AGENTS.md for project-wide rules

Where a skill is invoked on demand, AGENTS.md is loaded at startup and applied to every interaction in that environment. Use it for things that should be true regardless of which skill the agent picks: house style, forbidden paths, default libraries.

# AGENTS.md

You are the digest agent for the platform team.

## House rules
- Always write Markdown with `#` headers, never underline-style headers.
- Use UTC dates everywhere. Format: YYYY-MM-DD.
- Never modify files under /workspace/notes/. They are source-of-truth.
- When a step fails, stop and report; do not retry blindly.

## Defaults
- Python: prefer the standard library. If you must add a dependency, pin it.
- Shell: bash, not sh. Quote all variable expansions.

Mount it alongside the skill. The runtime concatenates AGENTS.md into the system prompt; your inline system_instruction stacks on top (both apply when present).

sources = [
    {
        "type": "inline",
        "target": ".agents/AGENTS.md",
        "content": open("AGENTS.md").read(),
    },
    {
        "type": "inline",
        "target": ".agents/skills/weekly-digest/SKILL.md",
        "content": open("weekly_digest_skill.md").read(),
    },
]

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Generate this week's digest from /workspace/notes.",
    system_instruction="Skip the Links appendix this run.",
    environment={"type": "remote", "sources": sources},
)

Notice the inline override: system_instruction is per-call, so you can branch behavior without rewriting the markdown files. It is the right place for one-off tweaks like "skip the appendix today".

Step 5: Persist as a managed agent

Inline sources are great for prototyping, but you do not want to push markdown into every request once the agent is stable. Promote the configuration to a named managed agent with client.agents.create — then you invoke it by ID and the platform forks the base environment for every run.

agent = client.agents.create(
    id="weekly-digest",
    base_agent="antigravity-preview-05-2026",
    description="Builds a weekly markdown digest from /workspace/notes.",
    system_instruction=(
        "You are the digest agent for the platform team. "
        "Follow AGENTS.md and the weekly-digest skill. Be concise."
    ),
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": open("AGENTS.md").read(),
            },
            {
                "type": "inline",
                "target": ".agents/skills/weekly-digest/SKILL.md",
                "content": open("weekly_digest_skill.md").read(),
            },
            # Pull a notes folder from a real repo on every fork.
            {
                "type": "repository",
                "source": "https://github.com/your-org/team-notes",
                "target": "/workspace/notes",
            },
        ],
    },
)

print("created:", agent.id)

Now invoke it like any other agent. Every call forks base_environment into a fresh sandbox, so each run starts clean — no leaked state from yesterday's digest.

result = client.interactions.create(
    agent="weekly-digest",
    input="Run the weekly digest for the last 7 days.",
    environment="remote",
)
print(result.output_text)

Need to override the persona for a single run? Pass system_instruction at call time and it stacks on the stored one. Need to limit tools for a security-sensitive call? Pass tools=[{"type":"code_execution"}] and the others fall away for that interaction only.

Step 6: Continue the conversation across turns

The API tracks two independent state dimensions: conversation history (previous_interaction_id) and sandbox files (environment). Resume both to keep going where you left off, with files intact.

turn1 = client.interactions.create(
    agent="weekly-digest",
    input="Run the digest for the platform team.",
    environment="remote",
)

turn2 = client.interactions.create(
    agent="weekly-digest",
    previous_interaction_id=turn1.id,
    environment=turn1.environment_id,
    input="Now produce a one-paragraph executive summary at the top.",
)

print(turn2.output_text)

If a long task creeps toward the model's context window, the harness performs automatic context compaction at around 135k tokens. You do not need to do anything — the agent keeps planning instead of erroring out. For very long runs use streaming so you can watch progress and cancel if it goes off the rails:

stream = client.interactions.create(
    agent="weekly-digest",
    input="Run the digest and also generate a CSV of action items.",
    environment="remote",
    stream=True,
)

for event in stream:
    # event has type, content, and any tool-call deltas
    print(event)

Common pitfalls

These trip up most first-time users. Working around them up front saves a lot of debugging.

• Wrong target path. Skills must live at .agents/skills/<name>/SKILL.md. The harness also scans /.agents/skills/ (with leading slash) but nothing else. A SKILL.md at the repo root is invisible.
• Frontmatter is non-optional. The planner reads name and description from YAML frontmatter. Without it the skill loads but never gets called, because the model cannot see what it does.
• Generation config is rejected. temperature, top_p, top_k, stop_sequences, and max_output_tokens all return HTTP 400. Antigravity is an agent loop, not a chat completion — temperature is fixed by the harness.
• No function calling, no MCP yet. If you need function_calling, file_search, computer_use, google_maps, or MCP servers, they are not supported on this agent in preview. Use the underlying Gemini 3.5 Flash model directly for those.
• Cost can run hot. A single interaction may accumulate 3M–5M tokens across the autonomous loop. Stream the run and cancel if the agent gets stuck, or scope the task narrowly. Data-processing runs are documented at $0.70–$3.25 per call.
• Environment forks on every invocation. Files written during one call are not in the next call's sandbox unless you reuse environment_id. Persist anything you need long-term to a GCS bucket or a Git repo and re-mount via sources.
• Outbound network defaults to open. Lock down with a network.allowlist in base_environment if your agent does not need the whole internet. The same block can inject auth headers for things like the GitHub API.
• Up to 1000 managed agents per project and only antigravity-preview-05-2026 is accepted as base_agent right now. Versioning and subagent nesting are not in yet.

Quick reference

Concept	What to know
Agent ID	antigravity-preview-05-2026 (only allowed base_agent in preview).
Endpoint	POST /v1beta/interactions with header Api-Revision: 2026-05-20.
Environment values	"remote" (fresh), env_id (reuse), or full config object.
Skill path	.agents/skills/<name>/SKILL.md
Default tools	code_execution, google_search, url_context, filesystem (via environment).
Source types	inline, repository (Git), or Cloud Storage.
Compaction	Auto at ~135k tokens; no action needed.
Multimodal input	Text and base64 images only — no audio, video, or documents yet.
Streaming	stream=True returns step deltas (text, reasoning, tool calls).
Pricing	Gemini 3.5 Flash tokens; compute free during preview. Typical task $0.25–$3.25.

Next steps

• Bundle several skills into a Git repo and mount the whole folder via a repository source. The harness scans recursively.
• Add a network.allowlist to scope the agent to your APIs only, with credentials injected via the transform block.
• Wire the Antigravity CLI (agy) to the same managed agent ID so your terminal and your code call into the same configured agent.
• Watch token usage per interaction in the AI Studio dashboard; set per-agent budgets in your app code by canceling streams that pass a threshold.
• When MCP support lands on the Antigravity agent (expected after the preview), the same SKILL.md format will likely host MCP tool registrations.

---

Antigravity Skills are the latest example of a converging pattern: vendors agreeing that the unit of agent capability extension is a markdown file with frontmatter. Get comfortable with the file layout now and you'll be ready when the next agent runtime ships the same convention.