Conventions Antigravity

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

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 Codex use.

No 1:1 mapping to Claude Code or Codex events. Specifically:

• Gemini's BeforeModel vs BeforeToolSelection distinction has no Claude/Codex analog — both fall under Claude's PreToolUse.
• Gemini has no equivalent of Claude's UserPromptSubmit or PermissionRequest.

I/O contract (Gemini lineage): JSON on stdin with session_id, transcript_path, cwd, hook_event_name, timestamp. JSON on stdout: systemMessage, decision ("allow"/"deny"), reason, continue, suppressOutput. Exit codes: 0 = ok, 2 = block (stderr = reason), other = warning.

Antigravity CLI hook event names: TBD — Google's transition post says "preserves hooks" without enumerating the event set. Treat the Gemini list as the current best guess.