# Creating Antigravity Skills

> Skill Architect for Antigravity. Activated when: creating a new skill, generating a skill, building agent capabilities, scaffolding a skill, improving a skill, polishing a skill, refactoring a skill, auditing a skill, fixing a skill, optimizing a skill, upgrading a skill, reviewing a skill, changelog, changes made. Creates and improves compliant SKILL.md files with supporting scripts, examples, and resources. Always delivers a structured Changes Made summary.

- Skill: `sharafmawjood/creating-antigravity-skills` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add sharafmawjood/creating-antigravity-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sharafmawjood/creating-antigravity-skills/raw
- Safety review: pending (external: skill-scanner PASS, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: SharafMawjood (https://skillmd.com/u/sharafmawjood)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/sharafmawjood/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:

| Stage | What Loads | When |
|-------|-----------|------|
| **Discovery** | Only `name` + `description` from YAML frontmatter | Every conversation start |
| **Activation** | Full `SKILL.md` body | When agent determines skill is relevant |
| **Execution** | `scripts/`, `references/`, `assets/` | On-demand during skill execution |

**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)

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

**Frontmatter rules:**

| Field | Constraints |
|-------|------------|
| `name` | 1–64 chars. Lowercase alphanumeric + hyphens only. Gerund form preferred. Defaults to folder name if omitted. |
| `description` | Max **1024 chars**. Third-person. Must list activation triggers/keywords explicitly. This is what the agent sees at Discovery stage. |

### Body Structure

Use this skeleton for the markdown body:

```markdown
# <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:

| Principle | Rule |
|-----------|------|
| **High-Density** | Skip definitions. Assume the agent knows the tech stack. No filler. |
| **500-Line / 5000-Token Rule** | `SKILL.md` stays concise. Move deep detail to `references/REFERENCE.md`. |
| **Bullet Points** | Use for heuristics, creative decisions, flexible guidance. |
| **Code Blocks** | Use for repeatable templates, exact file structures, output formats. |
| **CLI Commands** | Use for fragile, low-error-margin operations. Always include exact flags. |
| **Tables** | Use for lookup data, option matrices, rule summaries. |
| **Few-Shot Examples** | Include 1–2 input→output examples so the agent calibrates tone and format. |
| **Constraints** | Add explicit "Do not" rules for risky operations (e.g., "Do not run DELETE queries"). |

**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:

```markdown
## 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:

```markdown
### 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:

```markdown
### 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:

| Field | Question |
|-------|----------|
| **Purpose** | What does this skill do? |
| **Triggers** | What phrases/keywords should activate it? |
| **Scope** | Global (`~/.gemini/antigravity/skills/`) or project-local (`<project>/.agent/skills/`)? |
| **Dependencies** | Any scripts, APIs, or tools needed? |
| **Complexity** | Simple (SKILL.md only) or complex (with scripts/references/assets)? |

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)

| Need | Directory | Guideline |
|------|-----------|-----------|
| Automation / data processing | `scripts/<name>.py` | `argparse` + `--help`. One atomic action per script. |
| Shell automation | `scripts/<name>.sh` | Usage header. Self-contained. |
| Deep technical detail | `references/REFERENCE.md` | Loaded on-demand. Link directly from `SKILL.md`. |
| Structured data formats | `references/FORMS.md` | Schema definitions, JSON templates. |
| Usage demonstrations | `examples/<use-case>.md` | Complete, runnable examples. |
| Templates / static assets | `assets/<template>.md` or `.json` | Copy-paste ready. Use placeholder tokens. |

### Step 5: Validate

```bash
# 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:

```markdown
### 📂 <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

| Scope | Path | When to Use |
|-------|------|-------------|
| **Global** | `~/.gemini/antigravity/skills/<name>/` | Skill is useful across all projects (formatting, git workflows, code generation) |
| **Project-Local** | `<project-root>/.agent/skills/<name>/` | Skill is specific to one codebase (deploy scripts, DB management, project conventions) |

> [!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:

| Principle | Guidance |
|-----------|----------|
| **Modularity** | One skill = one focused capability. Break complex tasks into multiple skills. |
| **Self-Contained** | Skills should not rely on previous conversational context. |
| **Clear > Clever** | Prioritize clear textual instructions over complex scripts where possible. |
| **Token-Aware** | Every installed skill costs Discovery-stage tokens. Only create skills that are genuinely reusable. |
| **Relative Paths** | Use relative paths for internal references. Avoid absolute paths in skill content. |
| **Flat References** | All reference files link directly from `SKILL.md` — no A→B→C chains. |

---

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

| Check | What to Look For |
|-------|------------------|
| **Frontmatter** | `name` is 1–64 chars, lowercase alphanumeric + hyphens? `description` ≤1024 chars, keyword-rich, lists triggers? |
| **Structure** | Follows the directory hierarchy (Section 2)? Unnecessary files removed? |
| **Progressive Disclosure** | Heavy detail offloaded to `references/`? `SKILL.md` under 500 lines? |
| **Writing Quality** | No filler, no generic advice? High-density instructions? |
| **Missing Sections** | Has "When to Activate"? Few-shot examples? Constraints? Pre-Delivery Checklist? |
| **Operational Loop** | Includes Plan → Validate → Execute pattern? Error handling? |
| **Scripts** | Self-contained? Atomic? `--help` flag? `argparse` / usage header? |
| **Paths** | Uses relative paths internally? No hardcoded absolute paths? |
| **References** | Flat linking (no A→B→C chains)? All linked directly from `SKILL.md`? |

### Step 3: Generate Improvement Plan

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

```markdown
## 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:

| Issue | Fix |
|-------|-----|
| Missing/weak `description` | Rewrite with activation triggers and keywords |
| Missing "When to Activate" | Add section with explicit trigger conditions |
| SKILL.md too long (>500 lines) | Extract detail to `references/REFERENCE.md` |
| No few-shot examples | Add 1–2 input→output examples |
| No constraints | Add "Do not" rules for risky operations |
| No pre-delivery checklist | Add domain-specific checklist |
| Scripts missing `--help` | Add `argparse` with description and flags |
| Hardcoded absolute paths | Convert to relative paths |
| Nested reference chains | Flatten — link all refs directly from `SKILL.md` |
| Generic/filler content | Rewrite with high-density, actionable instructions |
| Missing operational loop | Add Plan → Validate → Execute pattern |
| Outdated conventions | Update to match latest official docs |

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

```markdown
## ✅ 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:**

```markdown
## ✅ 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.
```