--- name: create-update-antigravity-plugin description: > Use this skill when creating, updating, debugging, or publishing Google Antigravity plugins for the Antigravity App, Antigravity CLI (`agy`), and Antigravity IDE — scaffolding `plugin.json`, packaging `skills/`, `agents/`, `rules/`, `mcp_config.json`, `hooks.json`, and `sidecars/`, wiring hook payloads (`PreToolUse` decisions, `injectSteps`, `Stop` continuation), configuring Streamable HTTP or stdio MCP servers with Google ADC or OAuth, tuning rule triggers (`always_on`, `model_decision`, `glob`, `manual`), and installing locally, from GitHub, or from `antigravity-plugins-official`. Use when a plugin must load in `.agents/plugins/` or `~/.gemini/config/plugins/`, when `agy plugin list` shows missing components, when a rule is silently ignored, or when converting Codex/Claude packaging to Antigravity. license: MIT compatibility: antigravity, claude-code, codex, chatgpt, hermes, opencode, copilot metadata: audience: developers workflow: plugin-development --- # Google Antigravity Plugin Development An Antigravity plugin is a directory with a required `plugin.json` plus optional `skills/`, `agents/`, `rules/`, `mcp_config.json`, `hooks.json`, and `sidecars/`. It loads across the App, the CLI, and the IDE. ## Quick Start ```json title="plugin.json" { "$schema": "https://antigravity.google/schemas/v1/plugin.json", "name": "my-custom-plugin", "description": "A brief description of what my plugin does." } ``` ```text my-custom-plugin/ ├── plugin.json ├── skills/review-changes/SKILL.md ├── agents/code-auditor.md ├── rules/typescript.md ├── mcp_config.json └── hooks.json ``` Install by dropping the folder in `.agents/plugins/` (workspace) or `~/.gemini/config/plugins/` (global), or run `agy plugin install ./my-custom-plugin`. ## Manifest Only `name` and `description` exist; the schema is `additionalProperties: false`. - `name` — `^[a-zA-Z0-9-_]+$`, required for the CLI, defaults to the folder name in the App/IDE. Keep it kebab-case and equal to the folder. - `description` — shown in plugin listings. - **There is no `version` field.** Adding one fails schema validation. Version the release in `package.json`, a git tag, or the marketplace entry. - Do not copy Codex keys (`skills`, `author`, `interface`, `mcpServers`) into this file; both hosts use `plugin.json`, but their schemas are incompatible. Details: `references/plugin-manifest.md`. ## Skills `skills//SKILL.md`, frontmatter `name` (optional, defaults to the folder) and `description` (required — the only trigger). Discovery: `.agents/skills/` (legacy `.agent/skills`), `~/.gemini/config/skills/` in App/IDE, `~/.gemini/antigravity-cli/skills/` and `.../plugins//skills/` in the CLI. Every skill becomes a slash command in the CLI automatically, so there is no `commands/` directory: port a Claude `commands/.md` as a skill. Details: `references/components.md` §1. ## Subagents `agents/.md` with YAML frontmatter `name`, `description`, optional `tools`, `mainAgent`, `subagent`, `model` (`inherit|flash|pro`), `commandExecutionPolicy` (`off|auto|eager|sandbox`), `mcpServers`, `skills`/`plugins`. The body is the system prompt. An unmapped tool name in `tools` can hang the subagent — check names against the documented list. Nesting is capped at 10 levels; permission requests bubble to the parent UI. Details: `references/components.md` §2. ## Rules `rules/*.md` with mandatory frontmatter: ```yaml --- trigger: model_decision # always_on | model_decision | glob | manual description: "..." globs: "*.ts, *.tsx" # required only for glob --- ``` A missing or camelCase trigger is **silently discarded**. 24 KB per file after includes, 20,000-token aggregate budget, flat scanning of `rules/` unless `.agents/rules.json` lists nested paths. Use rules for invariants and skills for procedures. Details: `references/components.md` §3. ## MCP `mcp_config.json` at the plugin root (not `mcp.json`), root key `mcpServers`, one transport per server: `command` (+`args`/`env`/`cwd`) for stdio, or `serverUrl` (+`headers`) for Streamable HTTP. Legacy HTTP+SSE and `httpUrl` are unsupported. Auth: `authProviderType: "google_credentials"` for ADC, automatic OAuth with DCR, `oauth {clientId, clientSecret}` otherwise (redirect `https://antigravity.google/oauth-callback`), or static `headers`. Optional `disabled`, `enabledTools`, `disabledTools`, `timeoutSeconds`. Unconfigured MCP tools run in **Ask**; permissions use `mcp(server/tool)` with precedence Deny > Ask > Allow. Details: `references/mcp-and-permissions.md`. ## Hooks `hooks.json` maps a hook **name** to event arrays — the event is not the top-level key: ```json { "my-linter": { "PostToolUse": [ { "matcher": "run_command", "hooks": [ { "type": "command", "command": "./lint.sh", "timeout": 10 } ] } ] } } ``` Events: `SessionStart`, `PreToolUse`, `PostToolUse`, `PreInvocation`, `PostInvocation`, `Stop`. Input arrives on stdin as JSON; output must be JSON on stdout only. `PreToolUse` returns a `decision` (`allow|auto_approve|deny|ask|force_ask|deny_unless_prior_grant`) plus optional `reason`, `overwrite`, `permissionOverrides`. The three invocation/session events return `injectSteps`; `Stop` returns `{"decision": "continue"}` to keep going. Details and per-event payloads: `references/hooks-and-events.md`. ## Sidecars App-only background processes: `sidecars//sidecar.json` with `command` or `builtin: "schedule"`, `args`, `restart_policy`. Disabled until listed under `sidecars` in `~/.gemini/config/config.json`. Runtime data lives in `~/.gemini/antigravity/sidecar_data//` (`data/`, `logs/`, `events/`). Declare sidecars as unavailable on CLI and IDE. ## Surfaces and Distribution | Surface | Skills root | Notes | |---|---|---| | App | `.agents/skills/`, `~/.gemini/config/skills/` | Sidecars live here only | | CLI | `.agents/skills/`, `~/.gemini/antigravity-cli/skills/` | Auto slash commands | | IDE | `.agents/skills/`, `~/.gemini/config/skills/` | Customizations menu | ```bash agy plugin install @antigravity-plugins-official agy plugin install ./local-plugin agy plugin install https://github.com// agy plugin list --json agy plugin enable|disable|uninstall ``` App installs sync into the CLI's Installed tab. Details: `references/marketplace-and-distribution.md`. ## Gotchas - **`plugin.json` is shared with Codex but not compatible.** Different schema; one directory cannot serve both without a generated copy. - **No version field.** A `version` key invalidates the manifest. - **Name charset is permissive; keep kebab-case** so one identity works everywhere. - **Rules fail silently** on a bad `trigger`; there is no error surface. - **`mcp_config.json`, not `mcp.json`** — a wrong filename installs clean and exposes zero tools. - **`httpUrl` and HTTP+SSE are unsupported**; use `serverUrl` with Streamable HTTP. - **Hooks in CLI `settings.json` are ignored**; use `.agents/hooks.json`, `~/.gemini/config/hooks.json`, or the plugin's `hooks.json`. - **Hook stdout must be JSON only.** Logs on stdout break the decision contract. - **Sidecars are opt-in twice**: present in `sidecars/`, and enabled in `config.json`. - **No `bin/`, themes, or UI surface.** Native tools exist only through MCP. - **Absolute paths** (`/home/...`, `~`) in manifests, hooks, or MCP configs break portability across machines. ## Reference Triggers | Reference | When to use | File | |---|---|---| | Manifest & packaging | `plugin.json`, install paths, `agy plugin` | `references/plugin-manifest.md` | | Components | Skills, subagents, rules, sidecars | `references/components.md` | | Hooks | Event payloads, decisions, `injectSteps`, `Stop` | `references/hooks-and-events.md` | | MCP & permissions | Transports, auth, timeouts, permission syntax | `references/mcp-and-permissions.md` | | Distribution | Marketplace, git installs, surfaces, slash commands | `references/marketplace-and-distribution.md` | | Upstream coverage | Source mapping, known doc discrepancies, re-audit | `references/upstream-coverage.md` | | Upstream docs | Unmodified upstream pages (10 files, `` headers) | `references/docs/` | `references/docs/` holds the ten Antigravity pages this skill summarises, copied verbatim with a `` header. Load them when a rule here and the live docs disagree; `references/upstream-coverage.md` tracks what changed. ## Scripts `scripts/scaffold_plugin.ts --name [--with-hook] [--with-rule] [--with-agent]` creates a valid skeleton; `scripts/validate_plugin_structure.ts ` checks the manifest, components, hook shape, rule triggers, and subagent frontmatter; `scripts/validate_plugin_mcp.ts ` validates `mcp_config.json`. ## Validation Checklist - [ ] `plugin.json` parses, `name` matches the folder, no forbidden keys - [ ] `$schema` points at `https://antigravity.google/schemas/v1/plugin.json` - [ ] Every skill has `description` frontmatter - [ ] `rules/*.md` use a valid `trigger`; `glob` rules declare `globs` - [ ] `agents/*.md` declare `name` + `description`; `tools` names are real - [ ] `hooks.json` nests events under hook names; handlers set `command` - [ ] Hook scripts print JSON on stdout and finish inside `timeout` - [ ] `mcp_config.json` uses one transport per server, no `httpUrl` - [ ] No secrets or absolute paths in any manifest, hook, or MCP entry - [ ] `agy plugin list --json` reports the components you expect