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.

6. GEMINI.md (memory file — sophisticated hierarchy)

GEMINI.md is hierarchical: ~/.gemini/GEMINI.md → workspace + ancestor GEMINI.md files → JIT-discovered GEMINI.md on file access. All concatenated per prompt.

Distinctive features (versus AGENTS.md and CLAUDE.md):

• Supports @file.md imports via the Memory Import Processor. Verified 2026-05-26 against geminicli.com/docs/reference/memport/: imports nest (configurable max depth, default 5), accept any filename (not just GEMINI.md), and take relative or absolute paths. A GEMINI.md containing only @AGENTS.md resolves to AGENTS.md's full contents. validateImportPath restricts imports to allowed directories (repo-root siblings are fine).
• Filename is configurable via context.fileName in settings.json, which accepts an array — e.g., context.fileName: ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]. This is the official interop hook for AGENTS.md (Codex's canonical) and CLAUDE.md (Claude Code's canonical).

Recommended pattern for multi-tool projects (use context.fileName, NOT the @-import shim):

• Set context.fileName: ["AGENTS.md"] in .gemini/settings.json — makes Gemini/Antigravity read AGENTS.md directly. nlpm decision #5: AGENTS.md is the canonical universal memory file. nlpm itself ships this exact .gemini/settings.json.
• Why not rely on a GEMINI.md → @AGENTS.md shim? It works per the import-processor docs, but every documented example uses an explicit @./ / @../ prefix; the bare @AGENTS.md form (which Claude Code accepts natively in CLAUDE.md) is a valid relative path but unconfirmed against a live Gemini run. context.fileName has no such ambiguity — Gemini reads the named file directly with no import resolution involved.

7. MCP integration

Gemini reads MCP servers from mcpServers key inside ~/.gemini/settings.json or .gemini/settings.json (NOT a separate .mcp.json file). Standard MCP server shape: command, args, env. Also configurable inside gemini-extension.json for extension-bundled servers.

Slash commands: /mcp list, /mcp auth.

Antigravity CLI MCP layout: TBD.

8. Plugin marketplace

No central JSON marketplace manifest documented for Gemini CLI today. Discovery is via the Extensions Gallery at https://geminicli.com/extensions/ (community/partner/Google), GitHub-stars ranked, installed via gemini extensions install <github-url|path>.

Antigravity CLI marketplace layout: TBD.

github.com/google/skills is the official Google-published skills registry. Organized under skills/cloud/.... Installed via npx skills add google/skills. Cross-tool — targets Antigravity, Gemini CLI, Codex CLI, Claude Code, Cursor, and others.

9. Recent material changes (last 6 months)

10. Scope and uncertainty

This skill covers Antigravity CLI and legacy Gemini CLI conventions during the transition window. It does NOT cover:

• Universal SKILL.md spec → nlpm:conventions
• Penalty tables → nlpm:scoring
• Antigravity desktop IDE or Antigravity SDK (different artifact surfaces)

Major uncertainties — defer deep audit until resolved:

1. Singular .agent/ vs plural .agents/ — codelab uses singular for Antigravity workspace skills; agentskills.io cross-tool alias uses plural. Auditor should recognize both as valid.
2. npx skills verb — add per repo page, install per Cloud Next blog. add is canonical.
3. Antigravity directory-rename spec — Google's transition post says "not 1:1 parity" without enumerating gaps. Monitor for an official migration guide.
4. Antigravity-specific hook events — assumed to inherit Gemini's, but the transition post doesn't confirm.
5. github.com/google-antigravity/antigravity-cli — research surfaced this org/repo URL but the namespace differs from google/ proper. Verify before citing as authoritative.
6. "Antigravity plugins" manifest schema — renamed from Gemini "extensions" but full schema delta not published.
7. MCP support in Antigravity — not contradicted in the transition post, but not explicitly confirmed.

PR-B verification trigger: when Google publishes a stable Antigravity directory-layout spec (or when Antigravity overtakes Gemini CLI in real-world repo count), upgrade this skill from advisory to authoritative and add Antigravity-specific penalty rows to nlpm:scoring.