Skills & Runbooks

Skills are on-demand procedural playbooks and runbooks (e.g. how to deploy to Forgejo, how to run Docker migrations, or how to sanitize screenshot images).

---

The Kitchen Analogy: Rules vs. Skills

To understand how Antigravity manages your instructions without cluttering memory, think back to our restaurant kitchen:

• Rules (AGENTS.md):
  The Employee Handbook taped to the wall. Simple, always visible, and applies to everything: “Wash hands before cooking”, “Always use camelCase”.
• Skills (SKILL.md):
  The Specialty Recipe Book on the top shelf. You don’t read the 20-page recipe for chocolate soufflé while you’re flipping breakfast pancakes. You leave it on the shelf and only pull it down when a customer explicitly orders a soufflé.

---

The Power of Progressive Disclosure

If you put 20 complex multi-step procedures directly into AGENTS.md, you would burn 50,000+ tokens on every single chat turn—even when just asking a simple CSS question.

With Skills:

1. The agent only indexes a 1-line description in memory.
2. When chatting about unrelated topics, the skill consumes zero context tokens.
3. The moment your prompt matches the description, the agent dynamically pulls that specific SKILL.md off the shelf, follows the instructions, and puts it away.

[!TIP] You can verify this token efficiency visually in the Commands & Shortcuts chapter. Our /context inspector confirmed that active skills took only 777 tokens (0.1% of the entire window), with antigravity_guide/SKILL.md registering at just 44 tokens!

---

Real-World Case Study: The Image Redaction Skill

Here is a real example we created for this exact documentation site.

The Problem

We wanted to publish a screenshot of the /usage command, but it contained a private email address (Account: samo.blatnik@gmail.com). We needed to sanitize the image with a secure blur before uploading it.

Why not put it in AGENTS.md?

Putting Python image-processing libraries, pixel coordinates, and Gaussian blur theory in AGENTS.md would pollute the context window on every turn.

The Solution: Packaging It as a Skill

We created an image-redaction skill in .agents/skills/image-redaction/:

skills/image-redaction/
├── SKILL.md            # When and how to apply image sanitization
└── scripts/
    └── redact.py       # Reusable Python script using Pillow

1. The Skill Playbook (SKILL.md)

---
name: image-redaction
description: Securely redact, blur, or sanitize sensitive information (emails, API keys, passwords, IP addresses) in screenshot images using Python Pillow before public sharing or uploading.
---

# Image Redaction & Sanitization Skill

When an image contains sensitive data:
1. Locate the rectangular bounding box (x1, y1, x2, y2).
2. Apply Gaussian blur (radius >= 10) to permanently destroy character edges.
3. Run `python3 scripts/redact.py <image> --box <x1> <y1> <x2> <y2>`.
4. Visually inspect the output to ensure the text is unreadable while surrounding context remains intact.

2. The Reusable Helper Script (scripts/redact.py)

import argparse
from PIL import Image, ImageFilter

def redact(image_path, box, output_path, radius=10):
    im = Image.open(image_path).convert("RGBA")
    crop = im.crop(box)
    blurred = crop.filter(ImageFilter.GaussianBlur(radius))
    im.paste(blurred, box)
    im.save(output_path)

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("image")
    parser.add_argument("--box", nargs=4, type=int, required=True)
    parser.add_argument("-o", "--output")
    args = parser.parse_args()
    redact(args.image, tuple(args.box), args.output or args.image)

Now, whenever you ask: “Blur the email in this screenshot before we publish”, the agent automatically invokes this skill, runs the script with the exact bounding box, and delivers clean, sanitized assets!

---

Another Real Example: The Documentation Deployment Skill

We also created astro-starlight-deploy in .agents/skills/astro-starlight-deploy/:

• Encapsulates the entire workflow of non-interactive scaffolding (npm create astro@latest), modular chapter structuring, interactive LinkCard landing pages, and one-step Vercel production deployments.
• Contains an automated ./scripts/scaffold.sh helper to bootstrap ready-to-deploy doc sites in seconds.

---

Skills vs. Rules vs. Subagents

Concept	What It Is	Token Cost	Where It Lives
Rules (AGENTS.md)	Guardrails & style standards	Always active in context	Project root or ~/.config/AGENTS.md
Subagents	Autonomous workers with separate context	Zero in main chat	~/.gemini/config/agents/*.md
Skills (SKILL.md)	Step-by-step procedural recipes	Loaded only when triggered	.agents/skills/ or ~/.gemini/antigravity-cli/skills/

---

Discovery Tiers

• Workspace (.agents/skills/<name>/SKILL.md): Project-specific, committed to Git.
• Global CLI (~/.gemini/antigravity-cli/skills/<name>/SKILL.md): Available across all projects on this machine.
• Shared Gemini Suite (~/.gemini/skills/<name>/SKILL.md): Shared across Antigravity CLI and Antigravity IDE.

Type /skills in the TUI to inspect and manage all loaded skills.