From cd8922b617f0ec9b68ad4c1bc1d3bc112492ec28 Mon Sep 17 00:00:00 2001 From: ayobamiseun Date: Sun, 30 Aug 2026 00:17:37 +0100 Subject: [PATCH] docs(antigravity): document the command-wrapper discoverability limitation (#445) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Affected agy 1.1.x releases report the 8 legacy command TOMLs as converted to skills, but the converted wrappers never appear in the slash-command or skill catalog — plugin validate passing confirms the files are well formed, not that /build and the other wrappers exist. Replace the slash-command table with a wrapper-to-direct-invocation map (/agent-skills:, /agents for the webperf persona), note the wrapper-only behaviors that are unavailable (/build auto orchestration, /ship persona fan-out), warn against the YAML frontmatter workaround that breaks Gemini CLI's TOML parser, and add a post-install verification step. Align the README blurb with the same guidance. --- README.md | 2 +- docs/antigravity-setup.md | 34 ++++++++++++++++++---------------- 2 files changed, 19 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 4307eeed..582f74c9 100644 --- a/README.md +++ b/README.md @@ -107,7 +107,7 @@ Put workflow skills under `.cursor/skills/` (sync from `agent-skills/skills/`) a
Antigravity CLI -Install as a native plugin for skills, subagents, and slash commands. See [docs/antigravity-setup.md](docs/antigravity-setup.md). +Install as a native plugin for skills and subagents. In affected Antigravity CLI releases, legacy command TOMLs are reported as converted but their wrapper commands are not discoverable; invoke the underlying namespaced skills directly. See [docs/antigravity-setup.md](docs/antigravity-setup.md#lifecycle-workflows-and-command-compatibility). **Install from the repo:** diff --git a/docs/antigravity-setup.md b/docs/antigravity-setup.md index 6cd87eef..44b29352 100644 --- a/docs/antigravity-setup.md +++ b/docs/antigravity-setup.md @@ -1,12 +1,12 @@ # Using agent-skills with Antigravity CLI (agy) -The `agent-skills` package can be installed as a native plugin in the Antigravity CLI (`agy`), giving the agent access to structured workflows, personas, and custom slash commands. +The `agent-skills` package can be installed as a native plugin in the Antigravity CLI (`agy`), giving the agent access to structured workflows and personas. ## Setup ### Option 1: Native Plugin Installation (Recommended) -Antigravity CLI has a first-class plugin system that registers skills, agents, and custom commands. +Antigravity CLI has a first-class [plugin system](https://www.agy.dev/docs/plugins/) that registers skills and agents. The repository also carries legacy command TOMLs, but affected `agy` releases do not expose their converted wrappers; see [Lifecycle Workflows and Command Compatibility](#lifecycle-workflows-and-command-compatibility). **Install from the remote repository:** @@ -43,24 +43,24 @@ agy plugin list --- -## Slash Commands +## Lifecycle Workflows and Command Compatibility -The plugin registers 8 custom slash commands: 7 lifecycle commands plus the `/webperf` specialist audit: +Antigravity's [migration tooling](https://www.agy.dev/docs/cli/gcli-migration/) reports the 8 legacy definitions in `commands/*.toml` as "converted to skills." In affected `agy` 1.1.x releases, validation succeeds but the converted wrappers do not appear in the slash-command or skill catalog. A successful `agy plugin validate` therefore confirms the files are well formed, not that `/build` and the other short wrappers are available. This is tracked in [agent-skills #445](https://github.com/addyosmani/agent-skills/issues/445) and upstream in [antigravity-cli #788](https://github.com/google-antigravity/antigravity-cli/issues/788). -| Command | What it does | Activated Skill | -|---------|--------------|-----------------| -| `/spec` | Write a structured spec before writing code | `spec-driven-development` | -| `/planning` | Break work into small, verifiable tasks | `planning-and-task-breakdown` | -| `/build` | Implement the next task incrementally | `incremental-implementation` | -| `/test` | Run TDD workflow — red, green, refactor | `test-driven-development` | -| `/review` | Five-axis code review | `code-review-and-quality` | -| `/code-simplify` | Reduce complexity without changing behavior | `code-simplification` | -| `/ship` | Pre-launch checklist via parallel persona fan-out | `shipping-and-launch` | -| `/webperf` | Audit browser-facing apps for Core Web Vitals and performance issues | `web-performance-auditor` | +Use the native plugin skills directly while that importer limitation applies: -Each command automatically invokes the corresponding skill and guides the agent step-by-step. +| Intended wrapper | Direct Antigravity invocation | Notes | +|------------------|-------------------------------|-------| +| `/spec` | `/agent-skills:spec-driven-development` | Writes a structured spec before code | +| `/planning` | `/agent-skills:planning-and-task-breakdown` | Antigravity's built-in `/planning` command is a separate plan-mode control | +| `/build` | `/agent-skills:incremental-implementation` | Also invoke `/agent-skills:test-driven-development`; wrapper-only `/build auto` orchestration is unavailable | +| `/test` | `/agent-skills:test-driven-development` | Runs the red-green-refactor workflow | +| `/review` | `/agent-skills:code-review-and-quality` | Runs the five-axis review workflow | +| `/code-simplify` | `/agent-skills:code-simplification` | Simplifies without changing behavior | +| `/ship` | `/agent-skills:shipping-and-launch` | The wrapper's automatic persona fan-out is unavailable; invoke specialist agents separately | +| `/webperf` | Select `web-performance-auditor` from `/agents` | This workflow is a persona, not a skill | -> **Note:** Use `/planning` instead of `/plan` to avoid conflicts with Antigravity's internal plan-generation command. +Do not add YAML frontmatter to the TOML files as a workaround. Gemini CLI reads the parallel TOML command format with a strict parser, and `---` frontmatter makes those files invalid TOML without changing Antigravity's conversion behavior. --- @@ -79,6 +79,8 @@ To validate that your local plugin is correctly structured and contains all skil agy plugin validate /path/to/agent-skills ``` +Then start a fresh session and type `/agent-skills:` to inspect the namespaced skill catalog. If the validator reports that commands were converted but `/build` returns `No matches`, use the direct invocations above; reinstalling or adding a TOML `name` field does not resolve the known importer limitation. + --- ## How It Works