feat: add support for skills (#109)

Author: twishabansal

.github/workflows/skills-validate-fallback.yml

@@ -0,0 +1,37 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: lint
+
+on:
+  push:
+    paths-ignore:
+      - "skills/**"
+  pull_request:
+    paths-ignore:
+      - "skills/**"
+  pull_request_target:
+    types: [labeled]
+    paths-ignore:
+      - "skills/**"
+  workflow_dispatch:
+
+jobs:
+  skills-validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Skip Skill Validation
+        run: |
+          echo "No changes detected in 'skills/' directory. Skipping validation."
+          echo "This job ensures the required 'skills-validate' status check passes."

.github/workflows/skills-validate.yml

@@ -0,0 +1,56 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: Validate Skills
+
+on:
+  push:
+    paths:
+      - "skills/**"
+  pull_request:
+    paths:
+      - "skills/**"
+  pull_request_target:
+    types: [labeled]
+    paths:
+      - "skills/**"
+
+jobs:
+  skills-validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install skills-ref
+        run: |
+          pip install "git+https://github.com/agentskills/agentskills.git#subdirectory=skills-ref"
+
+      - name: Validate Skills
+        run: |
+          failed=0
+          for skill_dir in skills/*/; do
+            if [ -d "$skill_dir" ]; then
+              echo "Validating $skill_dir..."
+              if ! skills-ref validate "$skill_dir"; then
+                echo "Validation failed for $skill_dir"
+                failed=1
+              fi
+            fi
+          done
+          exit $failed

CLOUD-SQL-POSTGRESQL.md

@@ -13,7 +13,7 @@ To install this extension, the Gemini CLI version must be v0.6.0 or above. The v
 
 This section covers connecting to a Cloud SQL for PostgreSQL instance.
 
-1. **Verify Environment Variables**: The extension requires the following environment variables to be set before the Gemini CLI is started:
+1. **Extension Configuration**: This extension requires several settings (e.g., Project ID, Instance ID, Database Name, User, and Password). These values are gathered via prompts when you first install or link the extension:
 
     * `CLOUD_SQL_POSTGRES_PROJECT`: The GCP project ID.
     * `CLOUD_SQL_POSTGRES_REGION`: The region of your Cloud SQL instance.
@@ -22,6 +22,8 @@ This section covers connecting to a Cloud SQL for PostgreSQL instance.
     * `CLOUD_SQL_POSTGRES_USER`: The database username.
     * `CLOUD_SQL_POSTGRES_PASSWORD`: The password for the database user.
 
+    If you need to update any of these values later, use the `gemini extensions config cloud-sql-postgresql` command.
+
 2. **Handle Missing Variables**: If a command fails with an error message containing a placeholder like `${CLOUD_SQL_POSTGRES_PROJECT}`, it signifies a missing environment variable. Inform the user which variable is missing and instruct them to set it.
 
 3. **Handle Permission Errors**: If you encounter permission errors, ensure the user has the **Cloud SQL Client** (`roles/cloudsql.client`) role and the correct database-level permissions.
@@ -39,9 +41,9 @@ This section covers administrative operations like managing clusters, instances,
 
 ---
 
-# Additional Tools
+# Additional Extensions
 
-This section provides context on additional tools that can be recommended to the user based on their queries.
+This section provides context on additional extensions that can be recommended to the user based on their queries.
 
 #### Observability Extension
 
@@ -58,12 +60,12 @@ This section provides context on additional tools that can be recommended to the
 
 ## Connecting to New Resources
 
-When you create a new Cloud SQL for PostgreSQL instance, or database using the available tools, the connection is not automatically established. You will need to perform the following steps:
+When you create a new Cloud SQL for PostgreSQL instance, or database using the available skills, the connection is not automatically established. You will need to perform the following steps:
 
 1.  **(Optional) Save your conversation:** To avoid losing your progress, save the current session by running the command: `/chat save <your-tag>`
-2.  **Stop the CLI:** Terminate the Gemini CLI.
-3.  **Update Environment Variables:** Set or update your environment variables (e.g. `CLOUD_SQL_POSTGRES_DATABASE`, `CLOUD_SQL_POSTGRES_INSTANCE`) to point to the new resource.
-4.  **Restart:** Relaunch the Gemini CLI
+2. **Stop the CLI**: Terminate the Gemini CLI.
+3. **Update Extension Configuration**: Use the command `gemini extensions config cloud-sql-postgresql` to update your settings (e.g. `CLOUD_SQL_POSTGRES_DATABASE`, `CLOUD_SQL_POSTGRES_INSTANCE`) to point to the new resource.
+4. **Restart**: Relaunch the Gemini CLI
 5.  **(Optional) Resume conversation:** Resume your conversation with the command: `/chat resume <your-tag>`
 
 **Important:** Do not assume a connection to a newly created resource is active. Always follow the steps above to reconfigure your connection.
@@ -77,12 +79,13 @@ Users may have set project environment variables:
 *   `CLOUD_SQL_POSTGRES_INSTANCE`: The ID of the Cloud SQL for PostgreSQL instance.
 *   `CLOUD_SQL_POSTGRES_DATABASE`: The name of the database.
 
-Instead of prompting the user for these values for specific tool calls, prompt the user to verify reuse a specific value.
-Make sure to not use the environment variable name like `CLOUD_SQL_POSTGRES_PROJECT`, `${CLOUD_SQL_POSTGRES_PROJECT}`, or `$CLOUD_SQL_POSTGRES_PROJECT`. The value can be found by using command: `echo $CLOUD_SQL_POSTGRES_PROJECT`.
+Instead of prompting the user for these values for specific skill calls, prompt the user to verify the reuse of a specific setting value.
+Make sure to not use the environment variable name like `CLOUD_SQL_POSTGRES_PROJECT`, `${CLOUD_SQL_POSTGRES_PROJECT}`, or `$CLOUD_SQL_POSTGRES_PROJECT`. 
+The value can be verified by the user using the `gemini extensions config cloud-sql-postgresql` command or by checking their local settings.
 
 ## Use Full Table Name Format "DATABASE_NAME.SCHEMA_NAME.TABLE_NAME"
 
-**ALWAYS** use the full table name format, `DATABASE_NAME.SCHEMA_NAME.TABLE_NAME` in the generated SQL when using the `execute_sql` or `cloud_sql_postgresql__execute_sql` tool.
+**ALWAYS** use the full table name format, `DATABASE_NAME.SCHEMA_NAME.TABLE_NAME` in the generated SQL when executing the `execute_sql` script.
 * Default to using "public" for the schema name.
 * Use command `echo $CLOUD_SQL_POSTGRES_DATABASE` to get the current database value.
 
@@ -92,7 +95,7 @@ When working with AI features like vector embeddings in Cloud SQL, leverage the
 
 Embeddings can be generated using the `embedding()` function. For example: `embedding(<model_name>, <text_column_or_variable>)`.
 
-As an agent, if you do not know which model to use, you should use your tools to search for available and appropriate text embedding models compatible with the `google_ml_integration` extension (e.g., by searching for "Cloud SQL google_ml_integration supported models").
+As an agent, if you do not know which model to use, you should use your skills to search for available and appropriate text embedding models compatible with the `google_ml_integration` extension (e.g., by searching for "Cloud SQL google_ml_integration supported models").
 
 When performing similarity searches, remember to cast the result of the `embedding` function to the `vector` type. For example:
 `ORDER BY description_vector <-> embedding(<model_name>, $1)::vector`

DEVELOPER.md

@@ -43,7 +43,7 @@ The core logic for this extension is handled by a pre-built `toolbox` binary. Th
     extension from your local directory.
 
     ```bash
-    gemini extensions link .
+    gemini extensions install .
     ```
     The CLI will prompt you to confirm the installation. Accept it to proceed.
 

README.md

@@ -3,7 +3,7 @@
 > [!NOTE]
 > This extension is 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 [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 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.
 
 Learn more about [Gemini CLI Extensions](https://github.com/google-gemini/gemini-cli/blob/main/docs/extensions/index.md).
 > [!IMPORTANT]
@@ -57,9 +57,6 @@ You will be prompted to configure the following settings during installation. Th
 *   `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`.
 
-> [!NOTE]
-> This configuration is primarily for the Data Plane tools (querying). The Admin toolset does not strictly require these to be pre-set if you provide them in your prompts, but it is recommended for a smoother experience.
-
 To view or update your configuration:
 
 **List Settings:**
@@ -72,22 +69,10 @@ To view or update your configuration:
     *   `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.
 
-Alternatively, you can manually set these environment variables before starting the Gemini CLI:
-
-```bash
-export CLOUD_SQL_POSTGRES_PROJECT="<your-gcp-project-id>"
-export CLOUD_SQL_POSTGRES_REGION="<your-cloud-sql-region>"
-export CLOUD_SQL_POSTGRES_INSTANCE="<your-cloud-sql-instance-id>"
-export CLOUD_SQL_POSTGRES_DATABASE="<your-database-name>"
-export CLOUD_SQL_POSTGRES_USER="<your-database-user>"  # Optional
-export CLOUD_SQL_POSTGRES_PASSWORD="<your-database-password>"  # Optional
-export CLOUD_SQL_POSTGRES_IP_TYPE="PUBLIC" # Optional: `PUBLIC`, `PRIVATE`, `PSC`. Defaults to `PUBLIC`.
-```
-
 > [!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. 
+> * See [Troubleshooting](#troubleshooting) for debugging your configuration.
 
 ### Start Gemini CLI
 
@@ -116,43 +101,17 @@ Interact with Cloud SQL for PostgreSQL using natural language:
 * **Generate Code:**
   * "Generate a Python dataclass to represent the 'customers' table."
 
-## Supported Tools
-
-* **Admin:**
-    * `clone_instance`: Creates a clone for an existing Cloud SQL for PostgreSQL instance.
-    * `create_backup`: Creates a backup on a Cloud SQL instance.
-   	* `create_instance`: Use this tool to create an Postgres instance.
-   	* `create_user`: Use this tool to create Postgres-BUILT-IN or IAM-based users.
-    * `create_database`: Creates a new database in a Cloud SQL instance.
-   	* `get_instance`: Use this tool to get details about an Postgres instance.
-   	* `list_instances`: Use this tool to list instances in a given project and location.
-    * `list_databases`: Lists all databases for a Cloud SQL instance.
-    * `restore_backup`: Restores a backup of a Cloud SQL instance.
-    * `wait_for_operation`: Use this tool to poll the operations API until the operation is done.
-
-* **Data:**
-    * `list_tables`: Use this tool to lists tables in the database.
-    * `database_overview`: Use this tool to fetches the current state of the PostgreSQL server.
-    * `execute_sql`: Use this tool to executes a SQL query.
-    * `list_active_queries`: Use this tool to list currently running queries.
-    * `list_available_extensions`: Use this tool to list available extensions for installation.
-    * `list_installed_extensions`: Use this tool to list installed extensions.
-    * `get_query_plan`: Use this tool to get query plan.
-    * `list_autovacuum_configurations`: Use this tool to list autovacuum configurations and its value.
-    * `list_database_stats`: Use this tool to lists the key performance and activity statistics for each database in the postgreSQL instance.
-    * `list_indexes`: Use this tool to list available user indexes in a PostgreSQL database.
-    * `list_memory_configurations`: Use this tool to list memory configurations and its value.
-    * `list_pg_settings`: Use this tool to list configuration parameters for the PostgreSQL server.
-    * `list_publication_tables`: Use this tool to list publication tables in a PostgreSQL database.
-    * `list_replication_slots`: Use this tool to list replication slots.
-    * `list_roles`: Use this tool to lists all the user-created roles in PostgreSQL database.
-    * `list_schemas`: Use this tool to lists schemas in the database.
-    * `list_sequences`: Use this tool to list sequences in a PostgreSQL database.
-    * `list_tablespaces`: Use this tool to lists tablespaces in the database.
-    * `list_top_bloated_tables`: Use this tool to list top bloated tables.
-    * `list_triggers`: Use this tool to lists triggers in the database.
-    * `list_views`: Use this tool to lists views in the database from pg_views with a default limit of 50 rows.
-    * `list_invalid_indexes`: Use this tool to list invalid indexes.
+## Supported Skills
+
+This extension provides the following skills:
+
+* [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 Extensions
 

gemini-extension.json

@@ -2,24 +2,6 @@
   "name": "cloud-sql-postgresql",
   "version": "0.2.0",
   "description": "Create, connect, and interact with a Cloud SQL for PostgreSQL database and data.",
-  "mcpServers": {
-    "cloud_sql_postgresql_admin": {
-      "command": "${extensionPath}${/}toolbox",
-      "args": [
-        "--prebuilt",
-        "cloud-sql-postgres-admin",
-        "--stdio"
-      ]
-    },
-    "cloud_sql_postgresql": {
-      "command": "${extensionPath}${/}toolbox",
-      "args": [
-        "--prebuilt",
-        "cloud-sql-postgres",
-        "--stdio"
-      ]
-    }
-  },
   "contextFileName": "CLOUD-SQL-POSTGRESQL.md",
   "settings": [
     {