Creating Antigravity Skills

Skill Creator & Improver

Meta-skill for creating new and improving existing Antigravity skills. Follow these instructions exactly when asked to create, scaffold, build, improve, polish, audit, or refactor a skill.

When to Activate

• User says "create a skill", "new skill", "build a skill", "scaffold a skill"
• User says "improve a skill", "polish a skill", "fix a skill", "refactor a skill", "audit a skill"
• User references this skill by name or by /skill-creator
• User wants to add new agent capabilities to .agent/skills/ or ~/.gemini/antigravity/skills/
• User wants to upgrade an existing skill to follow Antigravity best practices

0. Mandatory: Reference Official Documentation

[!IMPORTANT] Before creating or improving ANY skill, you MUST first consult the official Antigravity skills documentation to ensure compliance with the latest standards.

Required steps every time:

1. Fetch the docs — Read the official documentation at:

   https://antigravity.google/docs/skills
   

   Use read_url_content, search_web, or the browser tool to retrieve the latest content.

2. Extract current standards — Identify any updates to:

   • YAML frontmatter fields and constraints
   • Directory structure conventions
   • Progressive disclosure requirements
   • Best practices or anti-patterns

3. Apply to your work — Cross-check your generated or improved skill against the official standards before delivery.

This step is non-negotiable. The official docs are the source of truth and may have changed since this skill was last updated.

1. Progressive Disclosure Model

Antigravity skills follow a three-stage loading pattern to minimize context-window usage:

Why this matters for skill authors:

• The description field is the sole basis for Discovery-stage matching — make it keyword-rich
• Keep SKILL.md lean (~500 lines / ~5000 tokens) so Activation doesn't bloat context
• Offload heavy detail to references/ or scripts/ so they load only when needed
• Avoid deeply nested reference chains — all reference files should link directly from SKILL.md

2. Structural Constraints

Every generated skill must follow this directory hierarchy:

<skill-dir>/<skill-name>/
├── SKILL.md              # Core instructions (REQUIRED)
├── scripts/              # Executable helpers (Python/Bash/JS)
│   └── *.py / *.sh
├── references/           # Deep-dive docs loaded on demand
│   └── REFERENCE.md / FORMS.md
├── examples/             # Usage demonstrations
│   └── *.md
└── assets/               # Templates, images, static data
    └── *.md / *.json / *.png

Rules:

• <skill-name> → lowercase alphanumeric + hyphens only, 1–64 chars (e.g., generating-api-hooks)
• SKILL.md is the only required file; other directories are created only when they add value
• Scripts must be self-contained and atomic (one well-defined action per script) with --help flags
• Use relative paths for all internal file references within the skill
• Keep SKILL.md under 500 lines / ~5000 tokens — offload complex logic to references/ or scripts/

3. SKILL.md Format

YAML Frontmatter (MANDATORY)

---
name: <gerund-verb>-<noun>       # e.g., generating-commit-messages
description: "<Third-person summary>. Activated when: <trigger1>, <trigger2>, <trigger3>. <What it does>."
---

Frontmatter rules:

Body Structure

Use this skeleton for the markdown body:

# <Skill Title>

<One-paragraph summary — goal, scope, and what the skill produces.>

## When to Activate
- <Trigger condition 1>
- <Trigger condition 2>

## Prerequisites
<Commands to verify dependencies. Omit section if none.>

## Workflow
### Step 1: <Phase Name>
<Instructions using the writing principles below.>

### Step 2: <Phase Name>
...

## Pre-Delivery Checklist
- [ ] <Validation item 1>
- [ ] <Validation item 2>

4. Writing Principles

Apply these when writing skill body content:

Anti-patterns to avoid:

• ❌ Walls of prose explaining obvious concepts
• ❌ Generic advice ("follow best practices")
• ❌ Duplicating information already in linked reference files
• ❌ Hardcoding absolute paths — use relative paths within the skill
• ❌ Deeply nested reference chains (A→B→C) — link everything directly from SKILL.md
• ❌ Installing too many irrelevant skills (increases Discovery-stage token cost)

5. Operational Loop: Plan → Validate → Execute

Every skill you generate must include this pattern embedded in its workflow:

5a. Checklist

Provide a [ ] markdown checklist the agent uses to track progress:

## Progress
- [ ] Analyzed user requirements
- [ ] Generated design / plan
- [ ] Validated output (dry-run / grep / lint)
- [ ] Executed final changes
- [ ] Ran pre-delivery checklist

5b. Validation Gate

Before any destructive or irreversible action, require the agent to run a check:

### Validate Before Executing
Run one of these before proceeding:
- `grep -r "pattern" .` to verify no conflicts
- `<script> --dry-run` to preview changes
- `cat <generated-file>` to review output

5c. Error Handling

Instruct the agent to self-recover:

### If Something Fails
1. Run `<script> --help` to check usage
2. Verify prerequisites are installed
3. Check file paths are correct (use absolute paths)
4. Re-read the relevant section of SKILL.md

6. Workflow: Creating a New Skill

When asked to create a skill, follow these steps exactly:

Step 1: Gather Requirements

Extract from the user's request:

If the user hasn't specified scope, ask. Default to project-local unless the user says "global" or "all projects".

Step 2: Generate the Skill Name

• Convert purpose to gerund form: "generate commit messages" → generating-commit-messages
• Lowercase alphanumeric + hyphens, 1–64 chars
• Verify no collision: ls <target-skills-dir>/

Step 3: Write SKILL.md

1. Write the YAML frontmatter (Section 3) — keyword-rich description for Discovery stage
2. Write the body following the skeleton (Section 3) and writing principles (Section 4)
3. Add few-shot examples where the task has variable output
4. Add explicit constraints / "Do not" rules for risky operations
5. Embed the Plan → Validate → Execute loop (Section 5)
6. Add a Pre-Delivery Checklist specific to the skill's domain

Step 4: Create Supporting Files (if needed)

Step 5: Validate

# Verify structure
find <skill-dir> -type f

# Verify SKILL.md frontmatter
head -5 <skill-dir>/SKILL.md

# Verify name is valid (1-64 chars, lowercase alphanumeric + hyphens)
echo "<skill-name>" | grep -E '^[a-z0-9][a-z0-9-]{0,63}$'

# Verify scripts are executable (if any)
python3 <skill-dir>/scripts/<script>.py --help 2>&1 || echo "Script check failed"

Step 6: Deliver with Changes Made Summary

Present the output in this exact format:

### 📂 <skill-name>
**Path:** `<full-path-to-skill-dir>/`

### SKILL.md
<full content of the SKILL.md file>

### Supporting Files
#### `scripts/<filename>`
<content>

#### `references/<filename>`
<content>

#### `examples/<filename>`
<content>

#### `assets/<filename>`
<content>

Then deliver the Changes Made summary (see Section 11).

7. Placement Guide

[!TIP] On Windows, the global path is C:\Users\<user>\.gemini\antigravity\skills\<name>\.

Decision rules:

• General capability → global (formatting, git workflows, code generation patterns)
• Project-specific architecture or conventions → project-local
• If unsure, start project-local — it's easier to promote to global later
• Be strategic about global skills — each one adds metadata tokens to every conversation's Discovery stage

8. Design Best Practices

Follow these principles from the official Antigravity documentation:

9. Workflow: Improving an Existing Skill

When asked to improve, polish, audit, or refactor an existing skill, follow these steps:

Step 1: Reference Official Docs (MANDATORY)

Follow Section 0 — fetch and read the official Antigravity skills documentation before making any changes.

Step 2: Audit the Existing Skill

Read the skill's full directory and evaluate against this checklist:

Step 3: Generate Improvement Plan

Present findings as a numbered list of issues with proposed fixes:

## Skill Audit: <skill-name>

### Issues Found
1. **[SEVERITY]** <issue description> → <proposed fix>
2. **[SEVERITY]** <issue description> → <proposed fix>
...

Severity: CRITICAL | HIGH | MEDIUM | LOW

Get user approval before making changes.

Step 4: Apply Improvements

Common improvement actions:

Step 5: Validate Improvements

Re-run the full Pre-Delivery Checklist (Section 10) against the improved skill.

Step 6: Deliver Changes Made Summary

Present the structured changelog (see Section 11). This is mandatory — never skip it.

10. Pre-Delivery Checklist

Before finalizing any created or improved skill, verify:

Structure

• SKILL.md exists with valid YAML frontmatter
• name is 1–64 chars, lowercase alphanumeric + hyphens only
• description is ≤1024 chars and lists activation triggers explicitly
• Directory follows the required hierarchy (Section 2)
• All internal references use relative paths

Content Quality

• SKILL.md is under 500 lines / ~5000 tokens
• No filler text or generic advice
• Includes "When to Activate" section
• Includes few-shot examples (if output is variable)
• Includes explicit constraints / "Do not" rules (if needed)
• Includes operational loop (checklist + validation + error handling)
• Includes Pre-Delivery Checklist for the generated skill's domain
• Heavy detail offloaded to references/ (not bloating SKILL.md)

Progressive Disclosure

• description is keyword-rich enough for accurate Discovery-stage matching
• Reference files are linked directly from SKILL.md (no nested chains)
• Scripts are loaded on-demand, not inlined in SKILL.md

Docs Compliance

• Official Antigravity docs were consulted before creating/improving this skill
• Skill aligns with the latest official standards and conventions

Scripts (if present)

• Each script has --help flag
• Scripts are self-contained and atomic (one action per script)
• Scripts use argparse (Python) or usage header (Bash)
• Dependency handling and error messages are clear

Examples (if present)

• Each example is a complete, runnable demonstration
• Examples cover both minimal and advanced use cases

Changes Made Summary

• Changes Made summary was delivered to the user (Section 11)
• Summary includes every file created or modified
• Summary includes clear descriptions of each change

11. Changes Made Summary (MANDATORY)

[!IMPORTANT] Every skill creation or improvement MUST end with a "Changes Made" summary. This is non-negotiable. Never skip this step.

After completing any skill work (create, improve, audit, polish, refactor), present the user with a structured summary of all changes:

## ✅ Changes Made

| # | File | Action | Detail |
|---|------|--------|--------|
| 1 | `SKILL.md` | Created / Modified | <what was done> |
| 2 | `scripts/search.py` | Created / Modified | <what was done> |
| 3 | `examples/minimal.md` | Created | <what was done> |

**Summary:** <1-2 sentence recap of the overall change>

Rules:

• List every file created, modified, or deleted
• Use the Action column: Created, Modified, Deleted, Moved, or Renamed
• The Detail column should be specific — not "updated file" but "added When to Activate section with 4 trigger conditions"
• End with a 1-2 sentence Summary of the overall impact
• For improvements, include before/after context where helpful

Example output:

## ✅ Changes Made

| # | File | Action | Detail |
|---|------|--------|--------|
| 1 | `SKILL.md` | Modified | Rewrote description with 8 activation triggers. Added Constraints section with 3 rules. Added Error Handling section. |
| 2 | `scripts/validate.py` | Created | New validation script with `--dry-run` and `--help` flags |
| 3 | `examples/basic.md` | Modified | Updated to match new SKILL.md workflow steps |

**Summary:** Improved skill discoverability, added safety constraints, and created a validation script for pre-delivery checks.