feat: add Claude Code plugin config and marketplace

Author: twishabansal

.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "spanner-marketplace",
+  "interface": {
+    "displayName": "Spanner Agent Skills"
+  },
+  "plugins": [
+    {
+      "name": "spanner",
+      "source": {
+        "source": "git",
+        "url": "https://github.com/gemini-cli-extensions/spanner.git"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Database"
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -0,0 +1,39 @@
+{
+  "name": "spanner",
+  "version": "0.2.6",
+  "description": "Connect and interact with Spanner data using natural language.",
+  "author": {
+    "name": "Google LLC",
+    "email": "data-cloud-ai-integrations@google.com"
+  },
+  "homepage": "https://cloud.google.com/spanner",
+  "license": "Apache-2.0",
+  "repository": "https://github.com/gemini-cli-extensions/spanner",
+  "skills": "./skills/",
+  "userConfig": {
+    "spanner_project": {
+      "title": "Project ID",
+      "description": "ID of the Google Cloud project",
+      "type": "string",
+      "sensitive": false
+    },
+    "spanner_instance": {
+      "title": "Instance",
+      "description": "ID of the Spanner instance",
+      "type": "string",
+      "sensitive": false
+    },
+    "spanner_database": {
+      "title": "Database",
+      "description": "ID of the Spanner database",
+      "type": "string",
+      "sensitive": false
+    },
+    "spanner_dialect": {
+      "title": "Database Dialect",
+      "description": "(Optional) The SQL dialect of the Spanner Database: 'googlesql' or 'postgresql'. (Default: 'googlesql')",
+      "type": "string",
+      "sensitive": false
+    }
+  }
+}

README.md

@@ -1,122 +1,251 @@
-# Gemini CLI Extension - Spanner
+# Spanner Agent Skills
 
 > [!NOTE]
-> This extension is currently in beta (pre-v1.0), and may see breaking changes until the first stable release (v1.0).
+> Currently in beta (pre-v1.0), and may see breaking changes until the first stable release (v1.0).
 
-This Gemini CLI extension provides a set of tools to interact with [Google Cloud Spanner](https://cloud.google.com/spanner/docs) instances. It allows you to manage your databases, execute queries, and explore schemas directly from the [Gemini CLI](https://google-gemini.github.io/gemini-cli/), using natural language prompts.
+This repository provides a set of agent skills to interact with [Google Cloud Spanner](https://cloud.google.com/spanner/docs) instances. These skills can be used with various AI agents, including [Gemini CLI](https://google-gemini.github.io/gemini-cli/), Claude Code, and Codex, to manage your databases, execute queries, explore schemas, and troubleshoot issues using natural language prompts.
 
-Learn more about [Gemini CLI Extensions](https://github.com/google-gemini/gemini-cli/blob/main/docs/extensions/index.md).
 > [!IMPORTANT]
 > **We Want Your Feedback!**
-> Please share your thoughts with us by filling out our feedback [form][form]. 
+> Please share your thoughts with us by filling out our feedback [form][form].
 > Your input is invaluable and helps us improve the project for everyone.
 
 [form]: https://docs.google.com/forms/d/e/1FAIpQLSfEGmLR46iipyNTgwTmIDJqzkAwDPXxbocpXpUbHXydiN1RTw/viewform?usp=pp_url&entry.157487=spanner
 
-## Why Use the Spanner Extension?
-
-* **Natural Language Management:** Stop wrestling with complex commands. Explore schemas and query data by describing what you want in plain English.
-* **Seamless Workflow:** As a Google-developed extension, it integrates seamlessly into the Gemini CLI environment. No need to constantly switch contexts for common database tasks.
-* **Code Generation:** Accelerate development by asking Gemini to generate data classes and other code snippets based on your table schemas.
-
+## Table of Contents
+
+- [Why Use Spanner Agent Skills?](#why-use-spanner-agent-skills)
+- [Prerequisites](#prerequisites)
+- [Getting Started](#getting-started)
+  - [Configuration](#configuration)
+  - [Installation & Usage](#installation--usage)
+    - [Gemini CLI](#gemini-cli)
+    - [Claude Code](#claude-code)
+    - [Codex](#codex)
+    - [Antigravity](#antigravity)
+- [Usage Examples](#usage-examples)
+- [Supported Skills](#supported-skills)
+- [Additional Agent Skills](#additional-agent-skills)
+- [Troubleshooting](#troubleshooting)
+
+## Why Use Spanner Agent Skills?
+
+- **Seamless Workflow:** Integrates seamlessly into your AI agent's environment. No need to constantly switch contexts for common database tasks.
+- **Natural Language Queries:** Stop wrestling with complex commands. Explore schemas and query data by describing what you want in plain English.
+- **Full Lifecycle Control:** Manage your Spanner databases, from exploring schemas to running queries.
+- **Code Generation:** Accelerate development by asking your agent to generate data classes and other code snippets based on your table schemas.
 
 ## Prerequisites
 
 Before you begin, ensure you have the following:
 
-* [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed with version **+v0.6.0**.
-* Setup Gemini CLI [Authentication](https://github.com/google-gemini/gemini-cli/tree/main?tab=readme-ov-file#-authentication-options).
-* A Google Cloud project with the **Spanner API** enabled.
-* Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment.
-* IAM Permissions
-    * Cloud Spanner Database Reader (`roles/spanner.databaseReader`)
-    * Cloud Spanner Database User (`roles/spanner.databaseUser`)
+- One of these AI agents installed
+  - [Gemini CLI](https://github.com/google-gemini/gemini-cli) version **v0.6.0** or higher
+  - [Claude Code](https://claude.com/product/claude-code) version **v2.1.94** or higher
+  - [Codex](https://developers.openai.com/codex) **v0.117.0** or higher
+  - [Antigravity](https://antigravity.google) **v1.14.2** or higher
+- A Google Cloud project with the **Spanner API** enabled.
+- Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment.
+- IAM Permissions:
+  - Cloud Spanner Database Reader (`roles/spanner.databaseReader`)
+  - Cloud Spanner Database User (`roles/spanner.databaseUser`)
 
 ## Getting Started
 
-### Installation
+### Configuration
 
-To install the extension, use the command:
+Please keep these env vars handy during the installation process:
 
-```bash
-gemini extensions install https://github.com/gemini-cli-extensions/spanner
-```
+- `SPANNER_PROJECT`: The GCP project ID.
+- `SPANNER_INSTANCE`: The Spanner instance ID.
+- `SPANNER_DATABASE`: The Spanner database ID.
+- `SPANNER_DIALECT`: (Optional) The SQL dialect of the Spanner Database: 'googlesql' or 'postgresql'. Defaults to "googlesql".
 
-### Configuration
+> [!NOTE]
+>
+> - Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment.
 
-You will be prompted to configure the following settings during installation. These settings are saved in an `.env` file within the extension's directory.
+### Installation & Usage
 
-*   `SPANNER_PROJECT`: The GCP project ID.
-*   `SPANNER_INSTANCE`: The Spanner instance ID.
-*   `SPANNER_DATABASE`: The Spanner database ID.
-*   `SPANNER_DIALECT`: (Optional) The SQL dialect of the Spanner database: 'googlesql' or 'postgresql'. Defaults to "googlesql".
+To start interacting with your database, install the skills for your preferred AI agent, then launch the agent and use natural language to ask questions or perform tasks.
 
-To view or update your configuration:
+For the latest version, check the [releases page][releases].
 
-**List Settings:**
-*   Terminal: `gemini extensions list`
-*   Gemini CLI: `/extensions list`
+[releases]: https://github.com/gemini-cli-extensions/spanner/releases
 
-**Update Settings:**
-*   Terminal: `gemini extensions config spanner [setting name] [--scope <scope>]`
-    *   `setting name`: (Optional) The single setting to configure.
-    *   `scope`: (Optional) The scope of the setting in (`user` or `workspace`). Defaults to `user`.
-*   Currently, you must restart the Gemini CLI for changes to take effect. We recommend using `gemini --resume` to resume your session.
+<!-- {x-release-please-start-version} -->
 
-Alternatively, you can manually set these environment variables before starting the Gemini CLI:
+<details open>
+<summary id="gemini-cli">Gemini CLI</summary>
+
+**1. Install the extension:**
 
 ```bash
-export SPANNER_PROJECT="<your-gcp-project-id>"
-export SPANNER_INSTANCE="<your-spanner-instance-id>"
-export SPANNER_DATABASE="<your-spanner-database-id>"
-export SPANNER_DIALECT="googlesql" # Optional: "googlesql" or "postgresql". Defaults to "googlesql".
+gemini extensions install https://github.com/gemini-cli-extensions/spanner
 ```
 
-> [!NOTE]
-> * Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment.
-> * See [Troubleshooting](#troubleshooting) for debugging your configuration.
+During the installation, enter your environment vars as described in the [configuration section](#configuration).
+
+**2. (Optional) Manage Configuration:**
+To view or update your configuration in Gemini CLI:
 
-### Start Gemini CLI
+- Terminal: `gemini extensions config spanner [setting name] [--scope <scope>]`
+- Gemini CLI: `/extensions list`
 
-To start the Gemini CLI, use the following command:
+**3. Start the agent:**
 
 ```bash
 gemini
 ```
 
+_(Tip: Run `/extensions list` to verify your configuration and active extensions.)_
+
 > [!WARNING]
 > **Changing Instance & Database Connections**
-> Currently, the database connection must be configured before starting the Gemini CLI and can not be changed during a session.
-> To save and resume conversation history use command: `/chat save <tag>` and `/chat resume <tag>`.
+> Currently, the database connection must be configured before starting the agent and can not be changed during a session.
+> To save and resume conversation history in Gemini CLI use command: `/chat save <tag>` and `/chat resume <tag>`.
+
+</details>
+
+<details>
+<summary id="claude-code">Claude Code</summary>
+
+**1. Set env vars:**
+In your terminal, set your environment vars as described in the [configuration section](#configuration).
+
+**2. Start the agent:**
+
+```bash
+claude
+```
+
+**3. Add the marketplace:**
+
+```bash
+/plugin marketplace add https://github.com/gemini-cli-extensions/spanner.git#0.2.6
+```
+
+**4. Install the plugin:**
+
+```bash
+/plugin install spanner@spanner-marketplace
+```
+
+_(Tip: Run `/plugin list` inside Claude Code to verify the plugin is active, or `/reload-plugins` if you just installed it.)_
+
+</details>
+
+<details>
+<summary id="codex">Codex</summary>
+
+**1. Clone the Repo:**
+
+```bash
+git clone --branch 0.2.6 git@github.com:gemini-cli-extensions/spanner.git
+```
+
+**2. Install the plugin:**
+
+```bash
+mkdir -p ~/.codex/plugins
+cp -R /absolute/path/to/spanner ~/.codex/plugins/spanner
+```
+
+**3. Set env vars:**
+Enter your environment vars as described in the [configuration section](#configuration).
+
+**4. Create or update marketplace.json:**
+`~/.agents/plugins/marketplace.json`
+
+```json
+{
+  "name": "my-data-cloud-google-marketplace",
+  "interface": {
+    "displayName": "Google Data Cloud Skills"
+  },
+  "plugins": [
+    {
+      "name": "spanner",
+      "source": {
+        "source": "local",
+        "path": "./plugins/spanner"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Database"
+    }
+  ]
+}
+```
+
+_(Tip: Run `codex plugin list` or use the `/plugins` interactive menu to verify your installed plugins.)_
+
+</details>
+
+<details>
+<summary id="antigravity">Antigravity</summary>
+
+**1. Clone the Repo:**
+
+```bash
+git clone --branch 0.2.6 https://github.com/gemini-cli-extensions/spanner.git
+```
+
+**2. Install the skills:**
+
+Choose a location for the skills:
+- **Global (all workspaces):** `~/.gemini/antigravity/skills/`
+- **Workspace-specific:** `<workspace-root>/.agents/skills/`
+
+Copy the skill folders from the cloned repository's `skills/` directory to your chosen location:
+
+```bash
+cp -R spanner/skills/* ~/.gemini/antigravity/skills/
+```
+
+**3. Set env vars:**
+Set your environment vars as described in the [configuration section](#configuration).
+
+_(Tip: Antigravity automatically discovers skills in these directories at the start of a session.)_
+
+</details>
+
+<!-- {x-release-please-end} -->
+
+## Usage Examples
+
+Interact with Spanner using natural language:
 
-## Usage
+- **Explore Schemas and Data:**
+  - "Show me all tables in the 'orders' database."
+  - "What are the columns in the 'products' table?"
+  - "How many orders were placed in the last 30 days, and what were the top 5 most purchased items?"
+- **Generate Code:**
+  - "Generate a Python dataclass to represent the 'customers' table."
 
-* **Explore Schemas and Data:**
-    * "Show me all tables in the 'orders' database."
-    * "What are the columns in the 'products' table?"
-    * "How many orders were placed in the last 30 days, and what were the top 5 most purchased items?"
+## Supported Skills
 
-* **Generate Code:**
-    * "Generate a Python dataclass to represent the 'customers' tab
+The following skills are available in this repository:
 
-## Supported Tools
+- [Spanner Data](./skills/spanner-data/SKILL.md) - Use these skills when you need to explore the database structure, discover schema objects like tables and graphs, and execute custom SQL queries to interact with your data.
 
-* `list_tables`: Use this tool to list tables and descriptions.
-* `list_graphs`: Use this tool to lists graphs in the database.
-* `execute_sql`: Use this tool to execute any SQL statement.
-* `execute_sql_dql`: Use this tool to execute DQL SQL statement.
+## Additional Agent Skills
 
-## Additional Extensions
+Find additional skills to support your entire software development lifecycle at [github.com/gemini-cli-extensions](https://github.com/gemini-cli-extensions), including:
 
-Find additional extensions to support your entire software development lifecycle at [github.com/gemini-cli-extensions](https://github.com/gemini-cli-extensions).
+- [Generic PostgreSQL skills](https://github.com/gemini-cli-extensions/postgres)
+- [Cloud SQL for PostgreSQL skills](https://github.com/gemini-cli-extensions/cloud-sql-postgresql)
+- and more!
 
 ## Troubleshooting
 
-Use `gemini --debug` to enable debugging.
+Use the debug mode of your agent (e.g., `gemini --debug`) to enable debugging.
 
 Common issues:
 
-* "failed to find default credentials: google: could not find default credentials.": Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. See [Set up Application Default Credentials](https://cloud.google.com/docs/authentication/external/set-up-adc) for more information.
-* "✖ Error during discovery for server: MCP error -32000: Connection closed": The database connection has not been established. Ensure your configuration is set via environment variables.
-* "✖ MCP ERROR: Error: spawn /Users/USER/.gemini/extensions/spanner/toolbox ENOENT": The Toolbox binary did not download correctly. Ensure you are using Gemini CLI v0.6.0+.
-* "cannot execute binary file": The Toolbox binary did not download correctly. Ensure the correct binary for your OS/Architecture has been downloaded. See [Installing the server](https://mcp-toolbox.dev/documentation/introduction/#install-toolbox) for more information.
+- "failed to find default credentials: google: could not find default credentials.": Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. See [Set up Application Default Credentials](https://cloud.google.com/docs/authentication/external/set-up-adc) for more information.
+- "✖ Error during discovery for server: MCP error -32000: Connection closed": The database connection has not been established. Ensure your configuration is set via environment variables.
+- "✖ MCP ERROR: Error: spawn .../toolbox ENOENT": The Toolbox binary did not download correctly. Ensure you are using the latest version of your agent.
+- "cannot execute binary file": The Toolbox binary did not download correctly. Ensure the correct binary for your OS/Architecture has been downloaded. See [Installing the server](https://mcp-toolbox.dev/documentation/introduction/#install-toolbox) for more information.