Merge #532: document the Antigravity command-wrapper difference

docs(antigravity): document the command-wrapper discoverability limitation (#445)

README.md

@@ -107,7 +107,7 @@ Put workflow skills under `.cursor/skills/` (sync from `agent-skills/skills/`) a
 <details>
 <summary><b>Antigravity CLI</b></summary>
 
-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:**
 

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