Skip to content

Antigravity path docs: official docs disagree with themselves; legacy .agent/skills and _agents/plugins alternates unhandled #6

Closed
Closed
Antigravity path docs: official docs disagree with themselves; legacy .agent/skills and _agents/plugins alternates unhandled#6

Description

@dandye
dandye
opened on Jul 28, 2026

Summary

While reproducing the config-directory confusion reported for this branch, I fetched and verified every path claim in docs/antigravity_runtimes_config.md against the live official docs (antigravity.google/docs/*, 2026-07-29). Two things fell out of that pass that aren't covered by the existing path-related issues (#3, #4):

Problems found

  1. The legacy .agent/skills/ (singular) backward-compat path is unhandled. The official Skills Overview states: "Antigravity now defaults to .agents/skills, but still maintains backward support for .agent/skills." scripts/install.py only ever writes to .agents/skills/ (plural), which is correct going forward, but this branch's docs previously didn't mention the legacy singular path at all — anyone debugging "why isn't my skill picked up" on an older Antigravity install had no pointer to check for it.

  2. The alternate _agents/plugins/ (underscore-prefixed) workspace path is unhandled and unverified. The official Plugins Spec lists _agents/plugins/ as an alternative to .agents/plugins/ for workspace-level plugin discovery. get_target_dir() in scripts/install.py hardcodes .agents/plugins/ only. If any Antigravity release actually scans _agents/plugins/ instead of (or in addition to) .agents/plugins/, a project-mode agy-dsk install could go silently undiscovered. Could not confirm from the docs which path a given release actually uses — needs a test against a real Desktop install.

Related context (already filed, not duplicated here)

Root cause behind all of the above

Google's own documentation disagrees with itself on the global standalone skills path depending on which page you land on: the general Skills Overview claims one universal path (~/.gemini/config/skills/) while the IDE-specific and CLI-specific pages each override it with their own distinct root (~/.gemini/antigravity/skills/ and ~/.gemini/antigravity-cli/skills/ respectively). That inconsistency in the official docs is almost certainly why the right config directory has been hard to pin down for this extension.

Full detail, a confirmed/inferred/unconfirmed annotation on every path, and the reference links (verified working, not hallucinated) are below.

Revised docs/antigravity_runtimes_config.md

# Antigravity Runtimes & Configuration Reference

This document details the directory locations, configuration file paths, and runtime behaviors across the three Google Antigravity product surfaces:
- **Antigravity 2.0 (Desktop Standalone App)**
- **Antigravity IDE (Visual Studio Code Extension / IDE Integration)**
- **Antigravity CLI (`agy`)**

Paths below are annotated **[CONFIRMED]** (fetched and quoted directly from the cited official page on 2026-07-29), **[INFERRED]** (a reasonable extrapolation from a confirmed pattern, not stated verbatim on any page we found), or **[UNCONFIRMED]** (referenced by this branch's code but not found on any official page we checked).

---

## Quick Comparison Matrix

| Feature / Location | Antigravity 2.0 (Desktop) | Antigravity IDE | Antigravity CLI (`agy`) |
| :--- | :--- | :--- | :--- |
| **Primary Interface** | Visual desktop application | VS Code / IDE extension | Terminal TUI |
| **Global Plugin Bundle Path** | `~/.gemini/config/plugins/<plugin-name>/` [CONFIRMED — docs/plugins] | `~/.gemini/config/plugins/<plugin-name>/` [CONFIRMED — docs/plugins; same universal path, not IDE-specific] | `~/.gemini/antigravity-cli/plugins/<plugin-name>/` [CONFIRMED — docs/cli/plugins] |
| **Workspace Plugin Bundle Path** | `<workspace-root>/.agents/plugins/<plugin-name>/` [CONFIRMED — docs/plugins] | same | Not applicable — CLI converts plugins to skills |
| **Global Standalone Skills Path** | `~/.gemini/config/skills/<skill-folder>/` [CONFIRMED — docs/skills, but see "Cross-Page Inconsistency" below] | `~/.gemini/antigravity/skills/<skill-folder>/` [CONFIRMED — docs/ide/skills] | `~/.gemini/antigravity-cli/skills/` [CONFIRMED — docs/cli/plugins] |
| **Workspace Standalone Skills Path** | `<workspace-root>/.agents/skills/<skill-folder>/` [CONFIRMED — docs/skills] | same | same [CONFIRMED — docs/cli/plugins] |
| **Legacy Skills Path (backward-compat)** | `<workspace-root>/.agent/skills/` (singular `.agent`) [CONFIRMED — docs/skills: *"Antigravity now defaults to .agents/skills, but still maintains backward support for .agent/skills"*] | same | not documented |
| **Alternate Workspace Plugin Path** | `_agents/plugins/` (underscore prefix) [CONFIRMED — docs/plugins, listed as an alternative to `.agents/plugins/`] | same | not applicable |
| **Global MCP Config Path** | `~/.gemini/config/mcp_config.json` (system-wide) [CONFIRMED — docs/mcp] or `~/.gemini/config/plugins/<plugin-name>/mcp_config.json` (plugin-scoped) [CONFIRMED — docs/plugins lists `mcp_config.json` as an optional plugin-bundle file] | `~/.gemini/antigravity/mcp_config.json` [INFERRED — parallels the confirmed IDE skills root; docs/mcp only states the universal global path] | `~/.gemini/antigravity-cli/mcp_config.json` [INFERRED — parallels the confirmed CLI skills root] |
| **Workspace MCP Config Path** | `<workspace-root>/.agents/mcp_config.json` [CONFIRMED — docs/mcp] | same | same |
| **OAuth Token Cache** | `~/.gemini/antigravity/mcp_oauth_tokens.json` [CONFIRMED — docs/mcp: *"Access tokens are stored in `~/.gemini/antigravity/mcp_oauth_tokens.json`. Expired tokens are refreshed automatically, and invalid tokens are removed."*] | same | not documented |
| **`~/.gemini/antigravity-ide/` directory** | n/a | **[UNCONFIRMED]** — not found on any official page we checked. Only appears in this repo's `scripts/install.py` (`get_profile_dir()`), where it's checked as a possible override of the IDE profile root. See "Deviations" below. | n/a |

---

## Cross-Page Inconsistency in Official Docs

Google's own documentation disagrees with itself on the **global standalone skills path**, depending on which page you read:

- The general [Antigravity Skills Overview](https://antigravity.google/docs/skills) states the global path (`~/.gemini/config/skills/<skill-folder>/`) applies **universally across Antigravity products** — it explicitly does not differentiate Desktop / IDE / CLI.
- The [Antigravity IDE Skills Guide](https://antigravity.google/docs/ide/skills) — a more specific page — gives a *different* global path for IDE: `~/.gemini/antigravity/skills/<skill-folder>/`.
- The [Antigravity CLI Plugins & Skills](https://antigravity.google/docs/cli/plugins) page gives yet another path, specific to CLI: `~/.gemini/antigravity-cli/skills/`.

Read together, the most consistent interpretation is: `~/.gemini/config/` is the Desktop-specific root, `~/.gemini/antigravity/` is the IDE-specific root, and `~/.gemini/antigravity-cli/` is the CLI-specific root — despite the general overview page's own wording suggesting one universal path. **This is very likely the source of the confusion in finding "the right config dir"** — the top-level skills doc reads as authoritative and universal, but the surface-specific pages silently override it.

`scripts/install.py` in this branch resolves paths the surface-specific way (three distinct roots), which matches empirical behavior better than the general overview page.

---

## Key Differences & Overlapping Paths

### 1. Plugin Bundling vs. Standalone Skills (Desktop Parity)
- **Plugin Bundles (Recommended)**: When a plugin manifest (`plugin.json`) is deployed to `~/.gemini/config/plugins/<plugin-name>/` (global) or `<workspace-root>/.agents/plugins/<plugin-name>/` (project), Antigravity Desktop automatically scans and registers all skills inside the plugin's `skills/` subdirectory. `plugin.json`'s `name` field is optional — it "defaults to the directory name if omitted" [CONFIRMED — docs/plugins].
- **Standalone Skills**: For IDE and CLI flavors (or simple standalone scripts), skills are installed directly into flavor-specific profile directories (`~/.gemini/antigravity/skills/` or `~/.gemini/antigravity-cli/skills/`).
- **Workspace Parity**: All three runtimes standardize on `<workspace-root>/.agents/skills/` for standalone project-level skills, with `.agent/skills/` (singular) kept only for backward compatibility.

### 2. Model Context Protocol (MCP) Resolution & Isolation
- **Plugin-Scoped MCP Config**: In Antigravity Desktop, plugins may define their own `mcp_config.json` directly inside their plugin root. Antigravity automatically loads these servers when the plugin is active, avoiding global `~/.gemini/config/mcp_config.json` namespace pollution.
- **Profile-Scoped MCP Config**: For IDE and CLI flavors, MCP configuration merges into their profile directories (`~/.gemini/antigravity/mcp_config.json` or `~/.gemini/antigravity-cli/mcp_config.json` — both **[INFERRED]**, see matrix above).
- **OAuth Token Cache**: `~/.gemini/antigravity/mcp_oauth_tokens.json` holds cached access tokens for `authProviderType: google_credentials` servers (like this extension's `google-security-operations` server). Useful first stop when debugging auth failures — expired tokens refresh automatically, invalid ones are pruned.
- **Safe Configuration Merging**: `scripts/install.py`'s `install_mcp_config()` reads the existing target `mcp_config.json`, merges in just the `google-security-operations` server entry, and writes back — it does not clobber other configured servers.

### 3. Legacy Gemini CLI Migration
- Legacy Gemini CLI workspace skills (`.gemini/skills/`) must be relocated to `.agents/skills/`.
- Legacy Gemini CLI extensions can be loaded natively as plugins by adding a `plugin.json` manifest alongside `gemini-extension.json`.
- Antigravity CLI supports "a one-time automated import of extensions, skills, and settings" from Gemini CLI [CONFIRMED — docs/cli/overview].

---

## Deviations & Gaps Found in This Branch

Cross-checking `scripts/install.py` against the confirmed paths above surfaced the following. The first two are filed as issues; the rest are new observations from this pass.

1. **`~/.gemini/antigravity-ide/` is unconfirmed and causes a real path split.** `get_profile_dir()` in `scripts/install.py` treats `~/.gemini/antigravity-ide/` as the IDE profile root *when it happens to exist*, but `get_target_dir()` (which decides where skills actually get installed) always uses `~/.gemini/antigravity/` for the `ide` flavor, with no equivalent override. Since no official page confirms `antigravity-ide` as a real directory, this branch should either drop the check entirely (align both functions on `~/.gemini/antigravity/`, the confirmed path) or confirm with Google whether `antigravity-ide` is a legitimate alternate profile for some IDE versions. Filed as [issue #4](https://github.com/gemini-cli-extensions/google-secops/issues/4).
2. **Project-mode `ide`/`cli` installs never substitute `${PROJECT_ID}` etc. in `rules/secops-environment.md`.** Unrelated to path confusion but adjacent — filed as [issue #3](https://github.com/gemini-cli-extensions/google-secops/issues/3).
3. **The legacy `.agent/skills/` (singular) backward-compat path is not handled anywhere in `install.py` or this doc's previous revision.** Not a bug in this branch (we only *write* the modern `.agents/skills/` path, which is correct going forward), but worth knowing if debugging why an agent isn't picking up a skill on an older Antigravity install that still reads the singular path.
4. **The alternate `_agents/plugins/` (underscore) workspace path is not handled.** `get_target_dir()` hardcodes `.agents/plugins/` for project-mode `agy-dsk` installs. If any Antigravity version actually expects `_agents/plugins/` instead, a project-mode plugin install would silently go undiscovered. We could not confirm from the docs which of `.agents/plugins/` or `_agents/plugins/` (or both) a given Antigravity release actually scans — worth an explicit test against a real Desktop install before relying on this path in documentation or support guidance.
5. **The OAuth token cache path (`~/.gemini/antigravity/mcp_oauth_tokens.json`) was previously undocumented locally.** Added above — it's the first place to check when `authProviderType: google_credentials` auth fails or a stale token needs clearing.

---

## Official Documentation References

All links below were fetched and verified on 2026-07-29.

1. **Agent Skills & Directory Specs**:
   - [Google Antigravity Skills Overview](https://antigravity.google/docs/skills) — universal skills paths, `.agent` → `.agents` migration note.
   - [Google Antigravity IDE Skills Guide](https://antigravity.google/docs/ide/skills) — IDE-specific global skills path, conflicts with the overview page (see "Cross-Page Inconsistency" above).
2. **MCP Configuration Specs**:
   - [Google Antigravity MCP Documentation](https://antigravity.google/docs/mcp) — global/workspace `mcp_config.json` paths, OAuth token cache location.
   - [Google Workspace Universal Search MCP Guide](https://developers.google.com/workspace/guides/universal-search-mcp) — not about Chronicle/SecOps; kept as a reference because it's a real Google-authored worked example of configuring an MCP server across Antigravity IDE, Antigravity 2.0, and Antigravity CLI side by side.
3. **Plugin Architecture & CLI Migration**:
   - [Google Antigravity Plugins Spec](https://antigravity.google/docs/plugins) — plugin discovery paths (including the `_agents/plugins/` alternate), required/optional plugin-bundle files.
   - [Google Antigravity CLI Overview & Migration](https://antigravity.google/docs/cli/overview) — what `agy` is, Gemini CLI import path, no directory paths given here.
   - [Google Antigravity CLI Using & Configuration](https://antigravity.google/docs/cli/using) — `settings.json` / `keybindings.json` locations (not skills/MCP — see cli/plugins for those).
   - [Google Antigravity CLI Plugins & Skills](https://antigravity.google/docs/cli/plugins) — CLI-specific plugin and skills paths.

Produced while critically reviewing PR #2 / branch agy_plugin_v0001 and researching why the right config directories have been hard to pin down.

Activity

  1. dandye commented on Jul 28, 2026

    @dandye
    dandye
    on Jul 28, 2026
    ContributorAuthor

    Correction (2026-07-29) — the "unconfirmed antigravity-ide" theory was wrong

    The doc originally posted in this issue flagged ~/.gemini/antigravity-ide/ as unconfirmed by any official page, and framed the whole problem as Google's docs contradicting themselves across pages. After discussion, I inspected a live machine running both Antigravity products, and the real story is more concrete than a docs error:

    Antigravity and Antigravity IDE are two separate, independently-installed, independently-versioned applications, each maintaining its own ~/.gemini/<app_data_dir>/ state directory:

    • ps aux shows two distinct language_server processes running concurrently: Desktop (/Applications/Antigravity.app, v2.4.3) launches with --app_data_dir antigravity --subclient_type hub; IDE (/Applications/Antigravity IDE.app, v2.1.1) launches with --app_data_dir antigravity-ide --subclient_type ide.
    • ~/.gemini/antigravity-ide/mcp_config.json is a real, standalone file; ~/.gemini/antigravity/mcp_config.json is a symlink into ~/.gemini/config/mcp_config.json — they are not interchangeable paths for the same product.
    • The --app_data_dir value is computed by Antigravity IDE's own shipped extension.js (an internal appDataDirectoryName property) — not a user-configurable flag, so this isn't a local experimentation artifact.
    • Also found: the docs/mcp page's claimed OAuth token path (~/.gemini/antigravity/mcp_oauth_tokens.json) does not exist on a live install at all. The only OAuth-token-shaped file found was ~/.gemini/antigravity-cli/antigravity-oauth-token — differently named, no .json extension.

    Practical effect on this branch: scripts/install.py's get_target_dir() currently sends the ide flavor to ~/.gemini/antigravity/skills/ — that's the Desktop app's directory, not the IDE app's. It should be ~/.gemini/antigravity-ide/skills/. This is the opposite of what the previous revision of this doc (and issue #4 as originally filed) recommended. See the corrected comment on #4.

    The revised docs/antigravity_runtimes_config.md below replaces the "Cross-Page Inconsistency" theory with this confirmed root cause (the cross-page inconsistency is still real and noted, just demoted to a secondary, non-primary cause).

    Revised docs/antigravity_runtimes_config.md (corrected 2026-07-29)

    # Antigravity Runtimes & Configuration Reference

This document details the directory locations, configuration file paths, and runtime behaviors across the three Google Antigravity product surfaces:
- **Antigravity 2.0 (Desktop Standalone App)**
- **Antigravity IDE (Visual Studio Code Extension / IDE Integration)**
- **Antigravity CLI (`agy`)**

Paths below are annotated **[CONFIRMED-DOC]** (fetched and quoted directly from the cited official page on 2026-07-29), **[CONFIRMED-LIVE]** (verified directly against a running installation on 2026-07-29 — see "Confirmed Root Cause" below), **[INFERRED]** (a reasonable extrapolation from a confirmed pattern, not directly verified), or **[UNCONFIRMED]** (referenced by this branch's code but not found on any official page or live install we checked).

**Update (2026-07-29, post-publication):** the original revision of this doc treated `~/.gemini/antigravity-ide/` as unconfirmed and recommended `install.py` drop it in favor of `~/.gemini/antigravity/`. Live process inspection on an actual machine running both products **reverses that recommendation** — see "Confirmed Root Cause" below. The matrix and deviations list have been corrected accordingly.

---

## Quick Comparison Matrix

| Feature / Location | Antigravity 2.0 (Desktop) | Antigravity IDE | Antigravity CLI (`agy`) |
| :--- | :--- | :--- | :--- |
| **Primary Interface** | Visual desktop application | VS Code / IDE extension | Terminal TUI |
| **Global Plugin Bundle Path** | `~/.gemini/config/plugins/<plugin-name>/` [CONFIRMED-DOC — docs/plugins] | `~/.gemini/config/plugins/<plugin-name>/` [CONFIRMED-DOC — docs/plugins; same universal path, not IDE-specific] | `~/.gemini/antigravity-cli/plugins/<plugin-name>/` [CONFIRMED-DOC — docs/cli/plugins] |
| **Workspace Plugin Bundle Path** | `<workspace-root>/.agents/plugins/<plugin-name>/` [CONFIRMED-DOC — docs/plugins] | same | Not applicable — CLI converts plugins to skills |
| **Global Standalone Skills Path** | `~/.gemini/config/skills/<skill-folder>/` [CONFIRMED-DOC — docs/skills, but see "Cross-Page Inconsistency" below] | `~/.gemini/antigravity-ide/skills/<skill-folder>/` [CONFIRMED-LIVE — the *running* Antigravity IDE process uses `--app_data_dir antigravity-ide`; the docs/ide/skills page instead says `~/.gemini/antigravity/skills/`, which is empirically wrong — that directory belongs to the separate Desktop app] | `~/.gemini/antigravity-cli/skills/` [CONFIRMED-DOC — docs/cli/plugins] |
| **Workspace Standalone Skills Path** | `<workspace-root>/.agents/skills/<skill-folder>/` [CONFIRMED-DOC — docs/skills] | same | same [CONFIRMED-DOC — docs/cli/plugins] |
| **Legacy Skills Path (backward-compat)** | `<workspace-root>/.agent/skills/` (singular `.agent`) [CONFIRMED-DOC — docs/skills: *"Antigravity now defaults to .agents/skills, but still maintains backward support for .agent/skills"*] | same | not documented |
| **Alternate Workspace Plugin Path** | `_agents/plugins/` (underscore prefix) [CONFIRMED-DOC — docs/plugins, listed as an alternative to `.agents/plugins/`] | same | not applicable |
| **Global MCP Config Path** | `~/.gemini/config/mcp_config.json` (system-wide) [CONFIRMED-DOC — docs/mcp] or `~/.gemini/config/plugins/<plugin-name>/mcp_config.json` (plugin-scoped) [CONFIRMED-DOC — docs/plugins lists `mcp_config.json` as an optional plugin-bundle file] | `~/.gemini/antigravity-ide/mcp_config.json` [CONFIRMED-LIVE — a real, non-symlinked `mcp_config.json` file exists at this path on a running install; `~/.gemini/antigravity/mcp_config.json` also exists but is a symlink into `~/.gemini/config/mcp_config.json` and belongs to the Desktop app] | `~/.gemini/antigravity-cli/mcp_config.json` [INFERRED — parallels the confirmed CLI skills root] |
| **Workspace MCP Config Path** | `<workspace-root>/.agents/mcp_config.json` [CONFIRMED-DOC — docs/mcp] | same | same |
| **OAuth Token Cache** | docs/mcp claims `~/.gemini/antigravity/mcp_oauth_tokens.json`, but **this file does not exist on a live install we checked** — neither `antigravity/` nor `antigravity-ide/` had any `*oauth*` file at all | same absence | `~/.gemini/antigravity-cli/antigravity-oauth-token` [CONFIRMED-LIVE — real file found by name, note it's *not* named `mcp_oauth_tokens.json` and has no `.json` extension, contra the docs/mcp page] |
| **`~/.gemini/antigravity-ide/` directory** | n/a | **[CONFIRMED-LIVE]** — this is the real, live, currently-in-use profile directory for the separate **Antigravity IDE** application (`/Applications/Antigravity IDE.app`, v2.1.1), distinct from **Antigravity** Desktop (`/Applications/Antigravity.app`, v2.4.3). Not a leftover, not unconfirmed — see "Confirmed Root Cause" below. | n/a |

---

## Confirmed Root Cause: Two Separate Applications, Not (Just) a Docs Error

The original theory here was that Google's docs simply contradict themselves across pages (see below — that's still true). But the deeper, empirically-confirmed cause is more concrete: **"Antigravity" and "Antigravity IDE" are two separate, independently-installed, independently-versioned applications**, each maintaining its own `~/.gemini/<app_data_dir>/` state tree. This was verified directly against a running machine on 2026-07-29, not inferred from docs:

- `ps aux` shows two distinct `language_server` processes running concurrently:
  - Antigravity Desktop: `/Applications/Antigravity.app/.../language_server --app_data_dir antigravity --subclient_type hub` (v2.4.3, bundle self-updated same day)
  - Antigravity IDE: `/Applications/Antigravity IDE.app/.../language_server_macos_arm --app_data_dir antigravity-ide --subclient_type ide` (v2.1.1, bundle last updated ~6 weeks prior)
- `~/.zshrc` carries two separate, independently-installer-generated PATH blocks (`# Added by Antigravity` / `# Added by Antigravity IDE`), pointing at two separate top-level install directories (`~/.antigravity/`, `~/.antigravity-ide/`), created three weeks apart.
- Antigravity IDE's shipped `extension.js` computes `--app_data_dir` from an internal `getInstance().appDataDirectoryName` property baked into the extension — it is not a user-supplied flag, environment variable, or something achievable via manual "isolate a profile" experimentation with `--app_data_dir`. (We considered and ruled out both "user experiment leftover" and "pre-2.0 legacy remnant" as explanations — the two apps carry fully independent version numbers and independent update cadences, which argues for two currently-maintained sibling products rather than one being a fossil of the other. We did not independently verify Google's product-naming history via release notes, so treat that last part as a reasonable inference, not a confirmed fact.)

**Practical takeaway:** the `ide` flavor in this extension should target the Antigravity IDE application's own directory, `~/.gemini/antigravity-ide/` — not `~/.gemini/antigravity/`, which belongs to the separate Desktop app. This reverses the original recommendation in this doc and in issue #4 (see "Deviations" below).

### Cross-Page Inconsistency in Official Docs (secondary, still true)

Independent of the above, Google's docs *also* disagree with themselves on the **global standalone skills path**, depending on which page you read:

- The general [Antigravity Skills Overview](https://antigravity.google/docs/skills) states the global path (`~/.gemini/config/skills/<skill-folder>/`) applies **universally across Antigravity products** — it explicitly does not differentiate Desktop / IDE / CLI.
- The [Antigravity IDE Skills Guide](https://antigravity.google/docs/ide/skills) — a more specific page — gives a *different* global path for IDE: `~/.gemini/antigravity/skills/<skill-folder>/`. We now know empirically this is **also wrong** — the live IDE app uses `antigravity-ide`, not `antigravity`.
- The [Antigravity CLI Plugins & Skills](https://antigravity.google/docs/cli/plugins) page gives a third path, specific to CLI: `~/.gemini/antigravity-cli/skills/` — this one checks out against the live install.

So the IDE-specific doc page itself appears to be stale or wrong, not just the general overview page glossing over per-surface differences. Trust the live process evidence above over any single doc page for the IDE flavor specifically.

---

## Key Differences & Overlapping Paths

### 1. Plugin Bundling vs. Standalone Skills (Desktop Parity)
- **Plugin Bundles (Recommended)**: When a plugin manifest (`plugin.json`) is deployed to `~/.gemini/config/plugins/<plugin-name>/` (global) or `<workspace-root>/.agents/plugins/<plugin-name>/` (project), Antigravity Desktop automatically scans and registers all skills inside the plugin's `skills/` subdirectory. `plugin.json`'s `name` field is optional — it "defaults to the directory name if omitted" [CONFIRMED-DOC — docs/plugins].
- **Standalone Skills**: For IDE and CLI flavors (or simple standalone scripts), skills are installed directly into flavor-specific profile directories — `~/.gemini/antigravity-ide/skills/` for IDE **[CONFIRMED-LIVE]**, `~/.gemini/antigravity-cli/skills/` for CLI.
- **Workspace Parity**: All three runtimes standardize on `<workspace-root>/.agents/skills/` for standalone project-level skills, with `.agent/skills/` (singular) kept only for backward compatibility.

### 2. Model Context Protocol (MCP) Resolution & Isolation
- **Plugin-Scoped MCP Config**: In Antigravity Desktop, plugins may define their own `mcp_config.json` directly inside their plugin root. Antigravity automatically loads these servers when the plugin is active, avoiding global `~/.gemini/config/mcp_config.json` namespace pollution.
- **Profile-Scoped MCP Config**: For IDE, MCP configuration merges into `~/.gemini/antigravity-ide/mcp_config.json` **[CONFIRMED-LIVE]** — not `~/.gemini/antigravity/`, which is the separate Desktop app's own directory. For CLI, `~/.gemini/antigravity-cli/mcp_config.json` **[INFERRED]**.
- **OAuth Token Cache**: docs/mcp claims `~/.gemini/antigravity/mcp_oauth_tokens.json`, but no such file was found on either `antigravity/` or `antigravity-ide/` on a live install — the only OAuth-token-shaped file found was `~/.gemini/antigravity-cli/antigravity-oauth-token` **[CONFIRMED-LIVE]**, a differently-named file. Treat the docs/mcp claim about this path with real skepticism until it's confirmed independently.
- **Safe Configuration Merging**: `scripts/install.py`'s `install_mcp_config()` reads the existing target `mcp_config.json`, merges in just the `google-security-operations` server entry, and writes back — it does not clobber other configured servers.

### 3. Legacy Gemini CLI Migration
- Legacy Gemini CLI workspace skills (`.gemini/skills/`) must be relocated to `.agents/skills/`.
- Legacy Gemini CLI extensions can be loaded natively as plugins by adding a `plugin.json` manifest alongside `gemini-extension.json`.
- Antigravity CLI supports "a one-time automated import of extensions, skills, and settings" from Gemini CLI [CONFIRMED-DOC — docs/cli/overview].

---

## Deviations & Gaps Found in This Branch

Cross-checking `scripts/install.py` against the confirmed paths above surfaced the following. The first two are filed as issues; the rest are new observations from this pass.

1. **`get_target_dir()` points the `ide` flavor at the wrong application's directory — CORRECTED 2026-07-29.** Live process inspection confirms `~/.gemini/antigravity-ide/` is the real, currently-in-use profile for the separate Antigravity IDE application, while `~/.gemini/antigravity/` belongs to the separate Antigravity Desktop app. That means `get_target_dir()`'s hardcoded `gemini_home / "antigravity" / "skills"` for the `ide` flavor is wrong — it should be `gemini_home / "antigravity-ide" / "skills"`. `get_profile_dir()`'s existing "prefer antigravity-ide if it exists" check had the right instinct but was only applied to the MCP-config half of the install, not the skills half, which is what produced the split. The original recommendation on this line (and in issue #4 as first filed) — "drop antigravity-ide, standardize on antigravity" — was **backwards** and has been corrected. Tracked in [issue #4](https://github.com/gemini-cli-extensions/google-secops/issues/4).
2. **Project-mode `ide`/`cli` installs never substitute `${PROJECT_ID}` etc. in `rules/secops-environment.md`.** Unrelated to path confusion but adjacent — filed as [issue #3](https://github.com/gemini-cli-extensions/google-secops/issues/3).
3. **The legacy `.agent/skills/` (singular) backward-compat path is not handled anywhere in `install.py` or this doc's previous revision.** Not a bug in this branch (we only *write* the modern `.agents/skills/` path, which is correct going forward), but worth knowing if debugging why an agent isn't picking up a skill on an older Antigravity install that still reads the singular path.
4. **The alternate `_agents/plugins/` (underscore) workspace path is not handled.** `get_target_dir()` hardcodes `.agents/plugins/` for project-mode `agy-dsk` installs. If any Antigravity version actually expects `_agents/plugins/` instead, a project-mode plugin install would silently go undiscovered. We could not confirm from the docs which of `.agents/plugins/` or `_agents/plugins/` (or both) a given Antigravity release actually scans — worth an explicit test against a real Desktop install before relying on this path in documentation or support guidance.
5. **The OAuth token cache path (`~/.gemini/antigravity/mcp_oauth_tokens.json`) was previously undocumented locally.** Added above — it's the first place to check when `authProviderType: google_credentials` auth fails or a stale token needs clearing.

---

## Official Documentation References

All links below were fetched and verified on 2026-07-29.

1. **Agent Skills & Directory Specs**:
   - [Google Antigravity Skills Overview](https://antigravity.google/docs/skills) — universal skills paths, `.agent` → `.agents` migration note.
   - [Google Antigravity IDE Skills Guide](https://antigravity.google/docs/ide/skills) — IDE-specific global skills path, conflicts with the overview page (see "Cross-Page Inconsistency" above).
2. **MCP Configuration Specs**:
   - [Google Antigravity MCP Documentation](https://antigravity.google/docs/mcp) — global/workspace `mcp_config.json` paths, OAuth token cache location.
   - [Google Workspace Universal Search MCP Guide](https://developers.google.com/workspace/guides/universal-search-mcp) — not about Chronicle/SecOps; kept as a reference because it's a real Google-authored worked example of configuring an MCP server across Antigravity IDE, Antigravity 2.0, and Antigravity CLI side by side.
3. **Plugin Architecture & CLI Migration**:
   - [Google Antigravity Plugins Spec](https://antigravity.google/docs/plugins) — plugin discovery paths (including the `_agents/plugins/` alternate), required/optional plugin-bundle files.
   - [Google Antigravity CLI Overview & Migration](https://antigravity.google/docs/cli/overview) — what `agy` is, Gemini CLI import path, no directory paths given here.
   - [Google Antigravity CLI Using & Configuration](https://antigravity.google/docs/cli/using) — `settings.json` / `keybindings.json` locations (not skills/MCP — see cli/plugins for those).
   - [Google Antigravity CLI Plugins & Skills](https://antigravity.google/docs/cli/plugins) — CLI-specific plugin and skills paths.

  2. dandye commented on Jul 29, 2026

    @dandye
    dandye
    on Jul 29, 2026
    ContributorAuthor

    Resolved in commit on agy_plugin_v0001 branch: updated docs/antigravity_runtimes_config.md with OAuth token cache location, backward-compat paths, and path resolution hierarchy explanations.

  3. dandye
    added a commit that references this issue on Jul 29, 2026

    docs: clarify Antigravity path resolution hierarchy, OAuth token cach…

    f2e9f82
  4. dandye
    closed this as completedon Jul 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions