docs: add Claude Code and Codex installation and usage instructions (#139)

Author: twishabansal

README.md

@@ -1,132 +1,237 @@
-# Gemini CLI Extension - Cloud SQL for PostgreSQL
+# Cloud SQL for PostgreSQL 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 skills to interact with [Cloud SQL for PostgreSQL](https://cloud.google.com/sql/docs/postgres) instances. It allows you to manage your databases, execute queries, explore schemas, and troubleshoot issues 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 [Cloud SQL for PostgreSQL](https://cloud.google.com/sql/docs/postgres) 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=cloud-sql-postgresql
 
-## Why Use the Cloud SQL for PostgreSQL Extension?
+## Table of Contents
 
-* **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.
-* **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 the entire lifecycle of your database, from creating instances to exploring schemas and running queries.
-* **Code Generation:** Accelerate development by asking Gemini to generate data classes and other code snippets based on your table schemas.
+- [Why Use Cloud SQL for PostgreSQL Agent Skills?](#why-use-cloud-sql-for-postgresql-agent-skills)
+- [Prerequisites](#prerequisites)
+- [Getting Started](#getting-started)
+  - [Configuration](#configuration)
+  - [Installation & Usage](#installation--usage)
+    - [Gemini CLI](#gemini-cli)
+    - [Claude Code](#claude-code)
+    - [Codex](#codex)
+- [Usage Examples](#usage-examples)
+- [Supported Skills](#supported-skills)
+- [Additional Agent Skills](#additional-agent-skills)
+- [Troubleshooting](#troubleshooting)
 
+## Why Use Cloud SQL for PostgreSQL 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 the entire lifecycle of your database, from creating instances to exploring schemas and 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 **Cloud SQL Admin API** enabled.
-* Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment.
-* IAM Permissions:
-  * Cloud SQL Client (`roles/cloudsql.client`)
-  * Cloud SQL Admin (`roles/cloudsql.admin`)
+- 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
+- A Google Cloud project with the **Cloud SQL Admin API** enabled.
+- Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment.
+- IAM Permissions:
+  - Cloud SQL Client (`roles/cloudsql.client`)
+  - Cloud SQL Admin (`roles/cloudsql.admin`)
+
 > [!NOTE]
-> If you do not configure a specific `CLOUD_SQL_POSTGRES_USER` or `CLOUD_SQL_POSTGRES_PASSWORD`, this extension defaults to using the active local IAM user credentials. You must also add the IAM user to your Cloud SQL instance, see [Creating a database user](https://cloud.google.com/sql/docs/postgres/add-manage-iam-users#creating-a-database-user).
+> If you do not configure a specific `CLOUD_SQL_POSTGRES_USER` or `CLOUD_SQL_POSTGRES_PASSWORD`, these skills default to using the active local IAM user credentials. You must also add the IAM user to your Cloud SQL instance, see [Creating a database user](https://cloud.google.com/sql/docs/postgres/add-manage-iam-users#creating-a-database-user).
 
 ## 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/cloud-sql-postgresql
-```
+- `CLOUD_SQL_POSTGRES_PROJECT`: The GCP project ID.
+- `CLOUD_SQL_POSTGRES_REGION`: The region of your Cloud SQL instance.
+- `CLOUD_SQL_POSTGRES_INSTANCE`: The ID of your Cloud SQL instance.
+- `CLOUD_SQL_POSTGRES_DATABASE`: The name of the database to connect to.
+- `CLOUD_SQL_POSTGRES_USER`: (Optional) The database username. Defaults to the active IAM user.
+- `CLOUD_SQL_POSTGRES_PASSWORD`: (Optional) The password for the database user.
+- `CLOUD_SQL_POSTGRES_IP_TYPE`: (Optional) Type of the IP address: `PUBLIC`, `PRIVATE`, or `PSC`. Defaults to `PUBLIC`.
 
-### Configuration
+> [!NOTE]
+>
+> - Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment.
+> - If your Cloud SQL for PostgreSQL instance uses private IPs, you must run your agent in the same Virtual Private Cloud (VPC) network.
 
-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
 
-*   `CLOUD_SQL_POSTGRES_PROJECT`: The GCP project ID.
-*   `CLOUD_SQL_POSTGRES_REGION`: The region of your Cloud SQL instance.
-*   `CLOUD_SQL_POSTGRES_INSTANCE`: The ID of your Cloud SQL instance.
-*   `CLOUD_SQL_POSTGRES_DATABASE`: The name of the database to connect to.
-*   `CLOUD_SQL_POSTGRES_USER`: (Optional) The database username. Defaults to the active IAM user.
-*   `CLOUD_SQL_POSTGRES_PASSWORD`: (Optional) The password for the database user.
-*   `CLOUD_SQL_POSTGRES_IP_TYPE`: (Optional) Type of the IP address: `PUBLIC`, `PRIVATE`, or `PSC`. Defaults to `PUBLIC`.
+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/cloud-sql-postgresql/releases
 
-**Update Settings:**
-*   Terminal: `gemini extensions config cloud-sql-postgresql [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} -->
 
-> [!NOTE]
-> * Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment.
-> * If your Cloud SQL for PostgreSQL instance uses private IPs, you must run Gemini CLI in the same Virtual Private Cloud (VPC) network.
-> * See [Troubleshooting](#troubleshooting) for debugging your configuration.
+<details open>
+<summary id="gemini-cli">Gemini CLI</summary>
+
+**1. Install the extension:**
+
+```bash
+gemini extensions install https://github.com/gemini-cli-extensions/cloud-sql-postgresql --ref 0.3.0
+```
 
-### Start Gemini CLI
+During the installation, enter your environment vars as described in the [configuration section](#configuration).
 
-To start the Gemini CLI, use the following command:
+**2. (Optional) Manage Configuration:**
+To view or update your configuration in Gemini CLI:
+
+- Terminal: `gemini extensions config cloud-sql-postgresql [setting name] [--scope <scope>]`
+- Gemini CLI: `/extensions list`
+
+**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/cloud-sql-postgresql.git#0.3.0
+```
+
+**4. Install the plugin:**
+
+```bash
+/plugin install cloud-sql-postgresql@cloud-sql-postgresql-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.3.0 git@github.com:gemini-cli-extensions/cloud-sql-postgresql.git
+```
+
+**2. Install the plugin:**
+
+```bash
+mkdir -p ~/.codex/plugins
+cp -R /absolute/path/to/cloud-sql-postgresql ~/.codex/plugins/cloud-sql-postgresql
+```
+
+**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": "cloud-sql-postgresql",
+      "source": {
+        "source": "local",
+        "path": "./plugins/cloud-sql-postgresql"
+      },
+      "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>
+
+<!-- {x-release-please-end} -->
 
 ## Usage Examples
 
 Interact with Cloud SQL for PostgreSQL using natural language:
 
-* **Provision Infrastructure:**
-    * "Create a new CLoud SQL for Postgres instance named 'e-commerce-prod' in the 'my-gcp-project' project."
-    * "Create a new user named 'analyst' with read access to all tables."
-* **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."
+- **Provision Infrastructure:**
+  - "Create a new Cloud SQL for Postgres instance named 'e-commerce-prod' in the 'my-gcp-project' project."
+  - "Create a new user named 'analyst' with read access to all tables."
+- **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."
 
 ## Supported Skills
 
-This extension provides the following skills:
+The following skills are available in this repository:
+
+- [Cloud SQL for PostgreSQL Admin](./skills/cloud-sql-postgres-admin/SKILL.md) - Use these skills when you need to provision new Cloud SQL instances, create databases and users, clone existing environments, and monitor the progress of long-running operations.
+- [Cloud SQL for PostgreSQL Data](./skills/cloud-sql-postgres-data/SKILL.md) - Use these skills when you need to explore the database structure, discover schema objects like views or stored procedures, and execute custom SQL queries to interact with your data.
+- [Cloud SQL for PostgreSQL Health](./skills/cloud-sql-postgres-health/SKILL.md) - Use these skills when you need to audit database health, identify storage bloat, find invalid indexes, analyze table statistics, and manage maintenance configurations like autovacuum.
+- [Cloud SQL for PostgreSQL Lifecycle](./skills/cloud-sql-postgres-lifecycle/SKILL.md) - Use these skills when you need to manage the lifecycle of your instances, including performing backups and restores, checking major version upgrade compatibility, and monitoring overall instance status.
+- [Cloud SQL for PostgreSQL Monitor](./skills/cloud-sql-postgres-monitor/SKILL.md) - Use these skills when you need to troubleshoot performance bottlenecks, analyze query execution plans, identify resource-heavy processes, and monitor system-level PromQL metrics.
+- [Cloud SQL for PostgreSQL Replication](./skills/cloud-sql-postgres-replication/SKILL.md) - Use these skills when you need to monitor replication health, manage sync states between nodes, and audit database roles and security settings to ensure environment integrity.
+- [Cloud SQL for PostgreSQL View Config](./skills/cloud-sql-postgres-view-config/SKILL.md) - Use these skills when you need to discover and manage PostgreSQL extensions or fine-tune engine-level settings such as memory allocation and server configuration parameters.
 
-* [Cloud SQL for PostgreSQL Admin](./skills/cloud-sql-postgres-admin/SKILL.md) - Use these tools when you need to provision new Cloud SQL instances, create databases and users, clone existing environments, and monitor the progress of long-running operations.
-* [Cloud SQL for PostgreSQL Data](./skills/cloud-sql-postgres-data/SKILL.md) - Use these tools when you need to explore the database structure, discover schema objects like views or stored procedures, and execute custom SQL queries to interact with your data.
-* [Cloud SQL for PostgreSQL Health](./skills/cloud-sql-postgres-health/SKILL.md) - Use these tools when you need to audit database health, identify storage bloat, find invalid indexes, analyze table statistics, and manage maintenance configurations like autovacuum.
-* [Cloud SQL for PostgreSQL Lifecycle](./skills/cloud-sql-postgres-lifecycle/SKILL.md) - Use these tools when you need to manage the lifecycle of your instances, including performing backups and restores, checking major version upgrade compatibility, and monitoring overall instance status.
-* [Cloud SQL for PostgreSQL Monitor](./skills/cloud-sql-postgres-monitor/SKILL.md) - Use these tools when you need to troubleshoot performance bottlenecks, analyze query execution plans, identify resource-heavy processes, and monitor system-level PromQL metrics.
-* [Cloud SQL for PostgreSQL Replication](./skills/cloud-sql-postgres-replication/SKILL.md) - Use these tools when you need to monitor replication health, manage sync states between nodes, and audit database roles and security settings to ensure environment integrity.
-* [Cloud SQL for PostgreSQL View Config](./skills/cloud-sql-postgres-view-config/SKILL.md) - Use these tools when you need to discover and manage PostgreSQL extensions or fine-tune engine-level settings such as memory allocation and server configuration parameters.
+## 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), including:
-* [Generic PostgreSQL extension](https://github.com/gemini-cli-extensions/postgres)
-* [Cloud SQL for PostgreSQL Observability extension](https://github.com/gemini-cli-extensions/cloud-sql-postgresql-observability)
-* and more!
+- [Generic PostgreSQL skills](https://github.com/gemini-cli-extensions/postgres)
+- [Cloud SQL for PostgreSQL Observability skills](https://github.com/gemini-cli-extensions/cloud-sql-postgresql-observability)
+- 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/cloud-sql-postgresql/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.

release-please-config.json

@@ -28,6 +28,7 @@
       "release-type": "simple",
       "package-name": "cloud-sql-postgresql",
       "extra-files": [
+        "README.md",
         {
           "type": "json",
           "path": "gemini-extension.json",