/conventions-antigravity

name: conventions-antigravity
description: "Antigravity and Gemini CLI artifact schemas: .gemini/ paths, extensions, hooks."
version: 0.1.0
user-invocable: false

Antigravity Conventions (with Gemini CLI legacy)

Tool-specific overlay for Google Antigravity CLI artifacts, including legacy Gemini CLI paths during the transition window. Loaded by the scorer and checker when an artifact is classified as **Tier 2-Antigravity** (per `agents/scorer.md` step 3). The universal floor lives in `nlpm:conventions`.

**Status:** Antigravity 2.0 was announced at Google I/O 2026 on **2026-05-19** (six days before this file was written). The directory layout is still settling, the official Antigravity-specific spec doc is sparse, and two authoritative research passes disagreed on `.agent/` (singular) vs `.agents/` (plural) as the canonical skills path. This skill is **advisory-only** for Antigravity-specific artifacts. PR-B verification trigger conditions are recorded in `analysis/multi-tool-design-2026-05.md`.

**Transition timeline:**

• **Now → 2026-06-18:** Gemini CLI continues serving AI Pro / Ultra / Free tiers in parallel with Antigravity CLI.
• **2026-06-18:** Gemini CLI sunsets for non-enterprise. Enterprise paid licenses retained.
• **After sunset:** Antigravity CLI is the sole successor; `.gemini/` paths fade to legacy.

**Primary authoritative sources:**

• <https://developers.googleblog.com/build-with-google-antigravity-our-new-agentic-development-platform/>
• <https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/>
• <https://antigravity.google/>
• <https://codelabs.developers.google.com/getting-started-with-antigravity-skills>
• <https://geminicli.com/docs/cli/skills/> (Gemini lineage; transitional)
• <https://geminicli.com/docs/hooks/reference/> (Gemini lineage; transitional)
• <https://github.com/google/skills>

---

1. File system layout

| Artifact | Project scope (Antigravity) | Project scope (Gemini, legacy) | User scope | |---|---|---|---| | Skills | `<workspace>/.agent/skills/<name>/SKILL.md` (singular — Antigravity per codelab); `.agents/skills/<name>/SKILL.md` (cross-tool alias, plural) | `.gemini/skills/<name>/SKILL.md` | `~/.gemini/antigravity/skills/` (transitional global) or `~/.gemini/skills/` (legacy) | | Slash commands | (under-documented for Antigravity) | `.gemini/commands/<name>.toml` | `~/.gemini/commands/` | | Hooks | (under-documented for Antigravity) | `.gemini/settings.json` → `hooks` object | `~/.gemini/settings.json` | | MCP servers | (under-documented for Antigravity) | `mcpServers` JSON key inside `.gemini/settings.json` | same | | Extensions / plugins | "Antigravity plugins" — `gemini-extension.json` (renamed in transition, layout TBD) | `~/.gemini/extensions/<name>/gemini-extension.json` | same | | Memory file | `GEMINI.md` (inherited; configurable via `context.fileName` array) | `GEMINI.md` (workspace + ancestors) | `~/.gemini/GEMINI.md` | | System config | TBD | `/etc/gemini-cli/settings.json` | — |

**Discovery precedence within a tier** (Gemini-lineage; assumed to carry over): built-in → extension → user → workspace. `.agents/skills/` beats `.gemini/skills/` (cross-tool path wins).

**Uncertainty (verify before scoring):**

• `<workspace>/.agent/skills/` (singular, from Antigravity codelab) vs `.agents/skills/` (plural, cross-tool alias from agentskills.io) — both may be true (Antigravity-specific singular path + cross-tool plural alias), or one may be a documentation error. Recommend recognizing both as valid skill paths.

---

2. SKILL.md (Tier 1, open spec — `name`, `description` required only)

Antigravity (and Gemini CLI) explicitly adopt the agentskills.io open standard. Required: `name`, `description`. Same as every other tool.

**Antigravity/Gemini-specific extensions** documented to date:

• `activate_skill` tool invocation (in-agent) to load a skill on demand.
• Mandatory user-consent prompt before injection (filesystem-access grant).
• `/skills` slash command (in-agent) lists installed skills.
• `gemini skills` terminal command (list/install/uninstall) — Gemini-only; Antigravity CLI uses `npx skills add` instead.

**Install verbs:**

• Cross-tool: `npx skills add github.com/google/skills` (per `github.com/google/skills` repo page).
• Legacy Cloud Next blog wording: `npx skills install` (treat as equivalent; `add` is the canonical command).
• Gemini CLI: `gemini extensions install <github-url|path>`.

---

3. `gemini-extension.json` (extension manifest, becoming "Antigravity plugin")

{
  "name": "my-extension",
  "version": "1.0.0",
  "mcpServers": { /* MCP server registrations */ },
  "contextFileName": "AGENTS.md",
  "excludeTools": ["WebFetch"]
}

Required: `name`, `version`. Notable optional: `mcpServers`, `contextFileName`, `excludeTools`. The rename to "Antigravity plugin" is announced; the manifest schema is documented to "preserve" extension semantics but Google hasn't published the full delta.

---

4. `.gemini/commands/<name>.toml` (slash commands — TOML)

prompt = """
Review the diff and check for {{args}}.
"""
description = "Custom code review with focus area"

**Required field:** `prompt`. **Optional:** `description` (auto-generated from filename if omitted).

**Template syntax** (Gemini-specific):

• `{{args}}` — raw argument injection.
• `!{shell command}` — runs shell, args auto-escaped.
• `@{path}` — file/directory injection. Respects `.gitignore` and `.geminiignore`. Supports PNG/JPEG/PDF/audio/video.

Subdirectory layout becomes a namespace: `.gemini/commands/ns/cmd.toml` → `/ns:cmd`.

**Antigravity CLI status:** unclear whether TOML slash commands carry over. Treat as legacy-only for now; Antigravity-specific command format TBD.

---

5. Hook events (Gemini lineage — fundamentally different from Claude/Codex)

Gemini (and inherited Antigravity) decomposes the lifecycle into Agent/Model/Tool layers, not the tool-centric model Claude and Co