Restructure the YAML frontmatter in all SKILL.md files to nest the 'category' field under the 'metadata:' block. The 'category' field is used to organize the skills in the README.md

PiperOrigin-RevId: 937616237
2026-09-14 20:00:20 +08:00 · 2026-06-24 16:15:47 -07:00
parent bb8b3e0b05
commit c75b500e4c
61 changed files with 289 additions and 20 deletions
@@ -9,8 +9,8 @@ description: >-
  events or conversions (use the data-manager-api-event-ingestion skill).
 metadata:
  version: 1.0
+  category: GoogleAds
 ---
-
 # Data Manager API Audience Ingestion

 ## Core Directives
@@ -98,11 +98,13 @@ for detailed installation instructions.

 1.  Navigate to the `data-manager-python` directory and install the utility
    library:
+    
    ```shell
    pip install .
    ```
 2.  Declare a dependency in your project's `requirements.txt` file (replacing
    `VERSION` with the identified version):
+    
    ```
   google-ads-datamanager-util=VERSION
    ```
@@ -111,6 +113,7 @@ for detailed installation instructions.

 1.  Navigate to the `data-manager-java` directory.
 2.  Build and publish the utility library to your local Maven repository:
+
   ```shell
   ./gradlew data-manager-util:install
   ```
@@ -132,20 +135,24 @@ for detailed installation instructions.
 ##### Node

 1.  Navigate to the `data-manager-node` directory and install dependencies:
+
   ```shell
   npm install
   ```
 2.  Navigate to the `util` directory:
+
   ```shell
   cd util
   ```
 3.  Pack the utility library into a `.tgz` archive:
+
   ```shell
   npm pack
   ```
 4.  Declare a dependency in your Node.js project's `package.json` pointing to
    the path of the generated `.tgz` archive (replacing `VERSION` with the
    identified version):
+
   ```json
   {
      "dependencies": {
@@ -158,11 +165,13 @@ for detailed installation instructions.

 1.  Navigate to the `data-manager-php` directory.
 2.  Resolve dependencies for the library:
+
   ```shell
   composer update --prefer-dist
   ```
 3.  Update your project's `composer.json` to declare a dependency on the utility
    library using a path repository:
+
   ```json
    {
        "repositories": [
@@ -181,6 +190,7 @@ for detailed installation instructions.

 In your .NET project, declare a `ProjectReference` dependency pointing to the
 cloned library's `.csproj` path:
+
 ```xml
 <ProjectReference Include="\path\to\cloned\Google.Ads.DataManager.Util\src\Google.Ads.DataManager.Util.csproj" />
 ```
@@ -245,6 +255,7 @@ Implement the ingestion logic using the following checkpoints:
    (emails, phone numbers, addresses).

    **Python Example:**
+    
    ```python
    from google.ads.datamanager_util import Formatter
    from google.ads.datamanager_util.format import Encoding
@@ -10,8 +10,8 @@ description: >-
  data-manager-api-audience-ingestion skill).
 metadata:
  version: 1.0
+  category: GoogleAds
 ---
-
 # Data Manager API Event Ingestion

 ## Core Directives
@@ -100,11 +100,13 @@ for detailed installation instructions.

 1.  Navigate to the `data-manager-python` directory and install the utility
    library:
+    
    ```shell
    pip install .
    ```
 2.  Declare a dependency in your project's `requirements.txt` file (replacing
    `VERSION` with the identified version):
+    
    ```
   google-ads-datamanager-util=VERSION
    ```
@@ -113,6 +115,7 @@ for detailed installation instructions.

 1.  Navigate to the `data-manager-java` directory.
 2.  Build and publish the utility library to your local Maven repository:
+
   ```shell
   ./gradlew data-manager-util:install
   ```
@@ -135,20 +138,24 @@ for detailed installation instructions.
 ##### Node

 1.  Navigate to the `data-manager-node` directory and install dependencies:
+
   ```shell
   npm install
   ```
 2.  Navigate to the `util` directory:
+
   ```shell
   cd util
   ```
 3.  Pack the utility library into a `.tgz` archive:
+
   ```shell
   npm pack
   ```
 4.  Declare a dependency in your Node.js project's `package.json` pointing to
    the path of the generated `.tgz` archive (replacing `VERSION` with the
    identified version):
+
   ```json
   {
      "dependencies": {
@@ -161,11 +168,13 @@ for detailed installation instructions.

 1.  Navigate to the `data-manager-php` directory.
 2.  Resolve dependencies for the library:
+
   ```shell
   composer update --prefer-dist
   ```
 3.  Update your project's `composer.json` to declare a dependency on the utility
    library using a path repository:
+
   ```json
    {
        "repositories": [
@@ -184,6 +193,7 @@ for detailed installation instructions.

 In your .NET project, declare a `ProjectReference` dependency pointing to the
 cloned library's `.csproj` path:
+
 ```xml
 <ProjectReference Include="\path\to\cloned\Google.Ads.DataManager.Util\src\Google.Ads.DataManager.Util.csproj" />
 ```
@@ -255,6 +265,7 @@ Implement the ingestion logic using the following checkpoints:
    (emails, phone numbers, addresses).

    **Python Example:**
+    
    ```python
    from google.ads.datamanager_util import Formatter
    from google.ads.datamanager_util.format import Encoding
@@ -8,8 +8,8 @@ compatibility:
 metadata:
  author: google-ads-api-team
  version: "1.0"
+  category: GoogleAds
 ---
-
 # Google Ads API MCP Server Installation

 This skill provides a structured setup guide to install, configure, and integrate the official open-source **[Google Ads Model Context Protocol (MCP) Server](https://github.com/googleads/google-ads-mcp)**.
@@ -55,6 +55,7 @@ The Google Ads MCP Server requires the same five parameters as the standard clie
    *   **Note:** Essential if your OAuth credentials belong to a Manager Account administrator rather than directly to the client account.

 ---
+
 *Once you have verified that all five parameters are present and formatted correctly, proceed to Step 2.*

 ## Step 2: Install Prerequisites (Python & pipx)
@@ -63,6 +64,7 @@ You **MUST** verify if the prerequisites are already installed before proposing

 ### 1. Verification Phase (Agent Action)
 You **MUST** run the following commands to check the environment:
+
 1.  Check Python version: `python3 --version` (Verify it is `3.12+`).
 2.  Check if pipx is installed: `pipx --version`.

@@ -77,6 +79,7 @@ Detect the operating system and propose the appropriate command to install `pipx

 #### macOS
 If the environment is macOS, propose:
+
 ```bash
 brew install pipx && pipx ensurepath
 # Or alternatively (if Homebrew is not installed):
@@ -85,6 +88,7 @@ pip install pipx && pipx ensurepath

 #### Windows (PowerShell)
 If the environment is Windows, propose:
+
 ```powershell
 scoop install pipx
 # Or alternatively:
@@ -93,6 +97,7 @@ pip install pipx && pipx ensurepath

 #### Linux (Ubuntu/Debian)
 If the environment is Linux, propose:
+
 ```bash
 sudo apt install pipx && pipx ensurepath
 ```
@@ -117,6 +122,7 @@ pipx install google-ads-mcp
 ```

 If the user explicitly requests the latest development version from GitHub, propose:
+
 ```bash
 # Install development version from GitHub (Only if explicitly requested)
 pipx install git+https://github.com/googleads/google-ads-mcp.git
@@ -125,6 +131,7 @@ pipx install git+https://github.com/googleads/google-ads-mcp.git
 ### 2. Verification Phase

 To verify the installation, execute:
+
 ```bash
 google-ads-mcp --help
 ```
@@ -133,8 +140,10 @@ google-ads-mcp --help
 `pipx` installs binaries into a specific local directory (typically `~/.local/bin`). If the user's shell configuration (e.g., `.bashrc` or `.zshrc`) hasn't been reloaded, `google-ads-mcp` might not be found in the current `PATH`.

 If `google-ads-mcp --help` fails with a "command not found" error:
+
 1. **DO NOT** assume the installation failed or get stuck in an installation loop.
 2. Verify the installation using the absolute path to the `pipx` binary directory:
+   
   ```bash
   ~/.local/bin/google-ads-mcp --help
   ```
@@ -150,6 +159,7 @@ If `google-ads-mcp --help` fails with a "command not found" error:
 > 3. [ ] **Explain Stdio Transport:** You **MUST** explicitly explain the communication architecture using the exact terminology: state that the MCP server communicates via the **Model Context Protocol (MCP)** using **standard input/output (`stdio`) transport**. Do not omit the words "standard input/output" or "transport".

 #### Key points to explain to the user regarding Stdio Transport:
+
 *   **Subprocess Execution:** The host client (e.g., Cursor, Claude Desktop) launches the MCP server as a background subprocess.
 *   **Command-Line Launch:** The host client must be configured with the exact command to run the server (`google-ads-mcp`) and the environment variables containing your Google Ads credentials.
 *   **No Network Ports:** Because it uses `stdio`, the server does not listen on a network port (like HTTP or WebSockets). Communication is handled entirely via stdin/stdout piping.
@@ -225,6 +235,7 @@ Add the server entry to your Claude configuration file.
    *   **Linux:** `~/.config/Claude/claude_desktop_config.json`

 *   **Configuration JSON:**
+    
    ```json
    {
      "mcpServers": {
@@ -250,6 +261,7 @@ Add the server entry to your Claude configuration file.
 ---

 ### 2. Cursor AI Editor
+
 1.  Open Cursor and navigate to: **Settings 🡒 Features 🡒 MCP**.
 2.  Click **+ New MCP Server**.
 3.  Configure the following fields:
@@ -276,12 +288,15 @@ When answering questions about connecting the Google Ads MCP server to Antigravi
 *   **No Custom Compilation**: Explicitly clarify that because Antigravity natively supports MCP, it **does not** require a separate custom plugin compilation or custom extension loading to use the MCP server.

 #### Verifying Activation in Antigravity CLI
+
 1.  **Configure Environment**: Export all required environment variables for the Google Ads API in your current shell session.
 2.  **Start Antigravity CLI**: Launch the CLI:
+    
    ```bash
    agy
    ```
 3.  **Verify MCP Status**: Inside the Antigravity CLI prompt, run the `/mcp` command to list active tools and servers:
+    
    ```text
    /mcp
    ```
@@ -297,19 +312,24 @@ When answering questions about connecting the Google Ads MCP server to Antigravi
 Instead of hosting this MCP server locally, you can host it on Google Cloud Run or on any other cloud-based infrastructure. This is useful if you want to share the server across different agents or run it as a web service.

 ### 1. Prerequisites
+
 1. A Google Cloud project.
 2. The [`gcloud` command-line tool](https://cloud.google.com/cli) installed, authenticated, and with an active project configured:
+   
   ```bash
   gcloud config set project YOUR_PROJECT_ID
   ```

 ### 2. Build and Push a Docker Image
 You can use Cloud Build to build and push the image to the Artifact Registry without needing Docker installed locally:
+
 1. Create a repository in Artifact Registry:
+   
   ```bash
   gcloud artifacts repositories create mcp-servers --repository-format=docker --location=us-central1
   ```
 2. Build and submit the image:
+   
   ```bash
   gcloud builds submit --tag us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest .
   ```
@@ -317,6 +337,7 @@ You can use Cloud Build to build and push the image to the Artifact Registry wit

 ### 3. Deploy to Google Cloud Run
 Deploy the container, ensuring you set `FASTMCP_HOST=0.0.0.0` and all required environment variables:
+
 ```bash
 gcloud run deploy google-ads-mcp \
  --image us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest \
@@ -328,6 +349,7 @@ gcloud run deploy google-ads-mcp \

 ### 4. Configure the MCP Client
 After deployment, update your MCP client configuration (for example, `~/.gemini/settings.json` or Claude/Cursor config) to use the Cloud Run URL:
+
 ```json
 {
  "mcpServers": {
@@ -356,6 +378,7 @@ the Antigravity CLI prompt:
 ```bash
 agy
 ```
+
 ```text
 /mcp
 ```
@@ -375,6 +398,7 @@ to replace `1234567890` with your actual Google Ads Customer ID (without hyphens

 ### 3. Expected Behavior (Success Criteria)
 A successful integration will trigger the following flow:
+
 1.  **Tool Discovery**: The AI assistant automatically detects the `google-ads-mcp`
    server tools.
 2.  **Execution**: The assistant formulates the parameters, calls the server via
@@ -385,6 +409,7 @@ A successful integration will trigger the following flow:

 ### 4. Troubleshooting
 If the assistant fails to retrieve the data or connect to the MCP server, check the following common failure points:
+
 *   **Authentication/Permission Errors (IDE Environment Gotcha)**: External IDEs (like Cursor or VS Code) often run in isolated environments or background processes that do not inherit shell RC files (e.g., `~/.bashrc` or `~/.zshrc`). Ensure your `GOOGLE_ADS_DEVELOPER_TOKEN`, OAuth client credentials, and `GOOGLE_ADS_REFRESH_TOKEN` are explicitly configured where the IDE can access them (prefer Method A: setting them directly in the MCP client's JSON configuration).
 *   **"Tools not found" / Mandatory Client Restart**: MCP servers are only loaded on application startup; changes to configuration files will not take effect dynamically. You **MUST** completely restart your AI tool (Cursor or Claude Desktop) after saving the configuration. Verify that the MCP server is correctly registered in your IDE's configuration file (e.g., the `mcpServers` block in Cursor's `project.json` or Claude Desktop's config).
 *   **PATH and Executable Issues (`spawn pipx ENOENT`)**: If the connection fails or logs show `spawn pipx ENOENT`, `pipx` is not in the system PATH of the IDE's environment. Provide the absolute path to `pipx` in the "command" field of your config (e.g., `/usr/local/bin/pipx` or `~/.local/bin/pipx`).
@@ -414,11 +439,13 @@ Once the Google Ads MCP Server is installed and successfully connected to your A
 When assisting a user or formulating queries, refer to the following tool definitions and best practices:

 ### 1. `list_accessible_customers`
+
 *   **Purpose:** Returns the list of Google Ads customer IDs and account names that are accessible to the authenticated user.
 *   **How to Use:** Call this tool first when starting a new session or when the target customer ID is unknown. It requires no arguments.
 *   **Example Intent:** *"What Google Ads accounts do I have access to?"*

 ### 2. `get_resource_metadata`
+
 *   **Purpose:** Retrieves detailed structural metadata about a specific Google Ads API resource type (e.g., `campaign`, `ad_group`, `customer`).
 *   **How to Use:** Call this tool to inspect the schema, available fields, metrics, and segments for a resource before constructing a GAQL query.
 *   **Arguments:**
@@ -426,6 +453,7 @@ When assisting a user or formulating queries, refer to the following tool defini
 *   **Example Intent:** *"What fields and metrics can I query for an ad group?"*

 ### 3. `search`
+
 *   **Purpose:** Executes a Google Ads Query Language (GAQL) query to fetch resource metrics, attributes, segments, and status.
 *   **How to Use:** Construct a valid GAQL query string based on the resource metadata and execute the search against a specific customer account.
 *   **Arguments:**
@@ -12,13 +12,14 @@ compatibility: "Outbound HTTPS connectivity required to access the Google Ads AP
 metadata:
  author: google-ads-api-team
  version: "1.0"
+  category: GoogleAds
 ---
-
 # Google Ads API Quickstart
 This skill guides you from absolute zero to running your first successful request to retrieve campaigns.

 ## Supported Tracks
 You can choose to use this skill with:
+
 1. **Official Client Libraries:** Python, Java, .NET, PHP, Ruby, or Perl.
 2. **Direct REST:** Raw HTTP REST requests.

@@ -30,6 +31,7 @@ You can choose to use this skill with:
 > To ensure the integration is secure, stable, and up-to-date, you must resolve all API and runtime versions dynamically. Do not rely on hardcoded defaults.

 ### Strict Constraints:
+
 *   **DO NOT Hardcode:** Never use hardcoded Google Ads API versions (e.g., `v24`) or language runtime versions (e.g., `Python 3.8+`, `Java 11+`) in generated code or environment setup instructions, unless the user explicitly requests a specific version.
 *   **MANDATORY Dynamic Resolution:** You must dynamically resolve the latest stable versions *at the start of execution* before generating any code or configuration, using the procedures detailed below.

@@ -37,9 +39,11 @@ You can choose to use this skill with:
 To ensure the integration is secure, stable, and up-to-date, you **MUST** resolve the absolute newest stable major version of the Google Ads API dynamically.

 #### Execution Steps:
+
 1.  **Pre-Flight Version Resolution:** Use your web search or URL-reading tools to inspect the latest entry in the [Google Ads API Release Notes](https://developers.google.com/google-ads/api/docs/release-notes.md.txt) or the highest versioned directory in the [Googleapis Github Repository](https://github.com/googleapis/googleapis/tree/master/google/ads/googleads) to resolve `RESOLVED_API_VERSION` (e.g., `v24`). If using Java, you **MUST** also resolve the latest stable release version of the Google Ads Java Client Library (referred to as `RESOLVED_LIBRARY_VERSION`, e.g., `34.0.0`).

 2.  **Mandatory Response Anchor:** You **MUST** output the following confirmation block as the **very first line** of your response to the user. Do not output any greeting, pleasantries, or introductory text before this block.
+    
    ```text
    [SYSTEM: Using Google Ads API version: RESOLVED_API_VERSION (Resolved from release notes)]
    ```
@@ -63,6 +67,7 @@ To ensure the integration is secure, stable, and up-to-date, you **MUST** resolv
 To prevent the generated setup guides from becoming obsolete due to language deprecation cycles, you **MUST** resolve language requirements dynamically.

 #### Execution Steps:
+
 1.  **Fetch Live Requirements:** Use your URL-reading tools to inspect the official [Google Ads Client Libraries - Supported Versions](https://developers.google.com/google-ads/api/docs/client-libs.md.txt#supported_api_versions) page.

 2.  **Extract Minimums:** Identify the minimum supported runtime version for the user's chosen language by scanning the Overview page or compatibility tables (e.g., looking for explicit requirements like Python 3.8+, Java 11+, .NET 6.0+, PHP 8.1+, Ruby 3.0+).
@@ -85,6 +90,7 @@ To prevent the generated setup guides from becoming obsolete due to language dep
 Before installing libraries or making API calls, you must obtain the five required authentication parameters.

 ### 1. Developer Token
+
 *   **Purpose:** Identifies your developer access and API quota.
 *   **How to Obtain:**
    1. Navigate directly to the **API Center** in your Google Ads Manager Account: https://ads.google.com/aw/apicenter *(Note: You must sign in with a Manager account, not a standard serving account)*.
@@ -94,6 +100,7 @@ Before installing libraries or making API calls, you must obtain the five requir
 > **Pending Token Restriction:** If your Developer Token status is "Pending" (unapproved), you **MUST ONLY** target **Google Ads Test Accounts**. Attempting to call a production account with a pending token will fail with the error: `DEVELOPER_TOKEN_NOT_APPROVED`.

 ### 2. OAuth2 Client ID & Client Secret
+
 *   **Purpose:** Identifies your application to Google's OAuth 2.0 server and allows you to request user authorization.
 *   **How to Obtain:**
    1. Open the [Google Cloud Console](https://console.cloud.google.com/).
@@ -112,6 +119,7 @@ Before installing libraries or making API calls, you must obtain the five requir
    6. **Download Secrets:** Click the download icon (JSON) next to your newly created Client ID. Save this file locally as `client_secrets.json`.

 ### 3. OAuth2 Refresh Token
+
 *   **Purpose:** Allows your application to obtain new access tokens automatically without requiring manual user login every hour.
 *   **How to Obtain:**
    You must run the Google Cloud (`gcloud`) CLI to generate your refresh token.
@@ -121,6 +129,7 @@ Before installing libraries or making API calls, you must obtain the five requir

    #### 2. Execute the Login Flow:
    Run the following command in your terminal, passing the path to the `client_secrets.json` file downloaded in the previous step:
+    
    ```bash
    gcloud auth application-default login \
      --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
@@ -136,6 +145,7 @@ Before installing libraries or making API calls, you must obtain the five requir
    Once successful, `gcloud` will output a message indicating where the credentials were saved (typically `~/.config/gcloud/application_default_credentials.json`). Open that file to copy your `refresh_token`.

 ### 4. Client Customer ID
+
 *   **Purpose:** The 10-digit ID of the specific Google Ads account you want to query or make changes to.
 *   **Format:** Must be 10 digits with **no hyphens** (e.g., `1234567890`, NOT `123-456-7890`).
 *   **How to Find It:** Log in to the Google Ads UI; the ID is displayed in the top-right corner next to your user icon.
@@ -146,6 +156,7 @@ Before installing libraries or making API calls, you must obtain the five requir
 ---

 ### 5. Login Customer ID
+
 *   **What it is:** The 10-digit Customer ID of the Google Ads Manager Account that owns or manages the target client account.
 *   **Format:** Must be 10 digits with **no hyphens** (e.g., `9876543210`).
 *   **When to Use:** This is **mandatory** if your OAuth credentials (and developer token) belong to a Manager Account, but you are querying a child/client account (Client Customer ID).
@@ -173,36 +184,42 @@ Developers can connect to the Google Ads API using either the official high-leve
 #### Python
 If you need to set up the Google Ads API environment for Python, do not guess the configuration.
 Instead, read the detailed setup guide:
+
 *   [Google Ads API Python Setup Reference](references/python.md)
 *(Package: `google-ads`)*

 #### Java
 If you need to set up the Google Ads API environment for Java, do not guess the configuration.
 Instead, read the detailed setup guide:
+
 *   [Google Ads API Java Setup Reference](references/java.md)
 *(Artifact: `com.google.api-ads:google-ads`)*

 #### .NET / C#
 If you need to set up the Google Ads API environment for .NET/C#, do not guess the configuration.
 Instead, read the detailed setup guide:
+
 *   [Google Ads API .NET Setup Reference](references/dotnet.md)
 *(Package: `Google.Ads.GoogleAds`)*

 #### PHP
 If you need to set up the Google Ads API environment for PHP, do not guess the configuration.
 Instead, read the detailed setup guide:
+
 *   [Google Ads API PHP Setup Reference](references/php.md)
 *(Package: `googleads/google-ads-php`)*

 #### Ruby
 If you need to set up the Google Ads API environment for Ruby, do not guess the configuration.
 Instead, read the detailed setup guide:
+
 *   [Google Ads API Ruby Setup Reference](references/ruby.md)
 *(Gem: `google-ads-ruby`)*

 #### Perl
 If you need to set up the Google Ads API environment for Perl, do not guess the configuration.
 Instead, read the detailed setup guide:
+
 *   [Google Ads API Perl Setup Reference](references/perl.md)
 *(Package: `Google::Ads::GoogleAds::Client`)*

@@ -218,6 +235,7 @@ Use this path if the user's environment does not support the official client lib
 #### REST (HTTP)
 If you need to set up the Google Ads API environment for REST (HTTP), do not guess the configuration.
 Instead, read the detailed setup guide:
+
 *   [Google Ads API REST Setup Reference](references/rest.md)
 *(Protocol: Raw HTTP POST JSON)*

@@ -246,6 +264,7 @@ Instead, read the detailed setup guide:

 #### Required Agent Response Checklist:
 When helping a user with this error, your response **MUST** include:
+
 1.  [ ] **Explain the Hierarchy:** Explain that the authenticating user likely belongs to a Manager Account that sits above the target client account.
 2.  [ ] **Provide the Fix:** Instruct the user to add their 10-digit Manager Account ID as the `login_customer_id` in their configuration file.
 3.  [ ] **Explain the Routing Logic:** Explain that `login_customer_id` tells the API to route the OAuth credentials through the manager account to validate access to the child account.
@@ -255,6 +274,7 @@ When helping a user with this error, your response **MUST** include:
 > **Security Guardrail:** Under no circumstances should you suggest exposing raw passwords, creating new unapproved developer tokens, or widening OAuth scopes beyond the standard `adwords` scope to bypass this error.

 #### Configuration Fix Example (`google-ads.yaml`):
+
 ```yaml
 developer_token: INSERT_DEVELOPER_TOKEN_HERE
 client_id: INSERT_OAUTH2_CLIENT_ID_HERE
@@ -272,6 +292,7 @@ login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE

 #### Required Agent Response Checklist:
 When helping a user with this error, your response **MUST** include:
+
 1.  [ ] **Explain the "Pending" Restriction:** Explain that an unapproved (Pending) developer token is fully functional but **restricted to Google Ads Test Accounts only**.
 2.  [ ] **Define Production Access Levels:** You **MUST** explicitly list all three access levels by name: state that targeting live production accounts requires the token to be approved for **Explorer Access**, **Basic Access**, or **Standard Access** by the Google Ads API compliance team. Do not condense or paraphrase this to "at least Basic Access".
 3.  [ ] **Provide Sandbox Setup Steps:** Guide the user on how to set up a sandbox environment:
@@ -8,8 +8,8 @@ description: Migrates Android applications from the old, legacy Google Mobile
  Android codebase from the old, legacy GMA SDK to GMA Next-Gen SDK.
 metadata:
  version: 1.1.0
+  category: GoogleAds
 ---
-
 # AI Migration Agent Instructions for the Google Mobile Ads SDK

 ## Migration Workflow
@@ -5,8 +5,8 @@ description: Provides instructions to implement, integrate, or configure
  when the task involves setting up banner ads in a mobile application.
 metadata:
  version: 1.0.0
+  category: GoogleAds
 ---
-
 # Google Mobile Ads SDK - Banner Ads

 Banner ads are rectangular image or text ads that occupy a spot within an app's
@@ -6,8 +6,8 @@ description: Provides instructions for integrating the Google Mobile Ads (GMA)
  SDK or mobile ads framework in an Android, iOS, or Unity application.
 metadata:
  version: 1.1.0
+  category: GoogleAds
 ---
-
 # Google Mobile Ads SDK - Install

 ## Workflow
@@ -6,8 +6,8 @@ description: Provides instructions for implementing, integrating, or configuring
  ads. Don't use for "rewarded interstitial" ads.
 metadata:
  version: 1.0.0
+  category: GoogleAds
 ---
-
 # Google Mobile Ads SDK - Interstitial Ads

 Interstitial ads show full-page ads for users on mobile apps. Interstitial ads
@@ -6,8 +6,8 @@ description: Provides instructions for implementing, integrating, or configuring
  ads. Don't use for "rewarded interstitial" ads.
 metadata:
  version: 1.0.0
+  category: GoogleAds
 ---
-
 # Google Mobile Ads SDK - Rewarded Ads

 Rewarded ads reward users with in-app items for interacting with full-screen
@@ -10,8 +10,8 @@ license: Apache-2.0
 metadata:
  author: Google LLC
  version: "1.0.0"
+  category: GoogleAds
 ---
-
 # IMA SDK basics

 The Google IMA SDK (Interactive Media Ads) lets you load in-stream video and
@@ -1,5 +1,7 @@
 ---
 name: agent-platform-alert-configuration
+metadata:
+  category: AiAndMachineLearning
 description: >-
  Configures best-practice alerting policies for Google Cloud Vertex AI / Agent
  Platform agents on Agent Runtime. Use when analyzing, writing, or deploying
@@ -1,5 +1,7 @@
 ---
 name: agent-platform-deploy
+metadata:
+  category: AiAndMachineLearning
 description: >-
  Deploy open models or custom weights from Model Garden to Agent Platform
  endpoints, check deployment status, verify serving endpoints, or clean up
@@ -1,5 +1,7 @@
 ---
 name: agent-platform-endpoint-management
+metadata:
+  category: AiAndMachineLearning
 description: >-
  Manages Agent Platform serving endpoints. Use when you need to create, list,
  describe, update, or delete serving endpoints for model deployment on Agent
@@ -48,11 +50,13 @@ correctly initialized by following these steps:
 1.  **Google Cloud Authentication**: Authenticate with your Google Cloud
    credentials and configure active Application Default Credentials (ADC) for
    Agent Platform access:
+    
    ```bash
    gcloud auth login
    gcloud auth application-default login
    ```
 2.  **Set Project**: Configure the active project for subsequent commands:
+    
    ```bash
    gcloud config set project $PROJECT_ID
    ```
@@ -1,5 +1,7 @@
 ---
 name: agent-platform-eval-flywheel
+metadata:
+  category: AiAndMachineLearning
 description: >-
  Measures and improves the quality of AI models and agents on Google Cloud
  using the Eval Quality Flywheel methodology. Use when evaluating an agent or
@@ -1,5 +1,7 @@
 ---
 name: agent-platform-inference
+metadata:
+  category: AiAndMachineLearning
 description: >-
  Connects to and performs inference with Google Cloud Agent Platform GenAI
  models, including First-Party Gemini models and Third-Party OpenMaaS models
@@ -53,26 +55,31 @@ environment is correctly initialized by following these steps:
 1.  **Google Cloud Authentication**: Authenticate with your Google Cloud
    credentials and configure active Application Default Credentials (ADC) for
    Agent Platform access:
+    
    ```bash
    gcloud auth login
    gcloud auth application-default login
    ```
 2.  **Enable API** (if not already enabled):
+    
    ```bash
    gcloud services enable aiplatform.googleapis.com
    ```
 3.  **Virtual Environment**: Create and activate a dedicated local virtual
    environment:
+    
    ```bash
    python3 -m venv .venv
    source .venv/bin/activate
    ```
 4.  **Install Dependencies**: Install the required SDKs:
+    
    ```bash
    pip install -r scripts/requirements.txt
    ```
 5.  **Verify Setup (Optional)**: Run all sample scripts at once to verify the
    environment is working end-to-end:
+    
    ```bash
    ./scripts/verify_all.sh
    ```
@@ -81,6 +88,7 @@ environment is correctly initialized by following these steps:
    activated first.

 <!-- disableFinding(LINE_OVER_80) -->
+
 > [!IMPORTANT]
 > **CRITICAL: Model IDs & Availability**
 > *   **Gemini Models**: See [Gemini Models][gemini-models-docs] for valid
@@ -226,6 +234,7 @@ complete code.
 > [!TIP]
 > **Alternative: Environment Variables**
 > You can set environment variables in your shell instead of updating the code.
+>
 > ```bash
 > export OPENAI_BASE_URL="https://aiplatform.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/global/endpoints/openapi"
 > export OPENAI_API_KEY="$(gcloud auth print-access-token)"
@@ -1,5 +1,7 @@
 ---
 name: agent-platform-migrate-from-ai-studio
+metadata:
+  category: AiAndMachineLearning
 description: >-
  Guides agents and users through migrating from Gemini API in Google AI Studio to Gemini Enterprise Agent Platform (formerly Vertex AI). Use this skill when moving applications to Google Cloud, to leverage Cloud credits, or to unify inferencing with other Cloud infrastructure (IAM, billing, telemetry).
 ---
@@ -1,5 +1,7 @@
 ---
 name: agent-platform-model-registry
+metadata:
+  category: AiAndMachineLearning
 description: >-
  Agent Platform Model Registry Management. Use when you need to upload, list,
  describe, update, or delete machine learning models (and their versions)
@@ -47,11 +49,13 @@ correctly initialized by following these steps:
 1.  **Google Cloud Authentication**: Authenticate with your Google Cloud
    credentials and configure active Application Default Credentials (ADC) for
    Agent Platform access:
+    
    ```bash
    gcloud auth login
    gcloud auth application-default login
    ```
 2.  **Set Project**: Configure the active project for subsequent commands:
+    
    ```bash
    gcloud config set project $PROJECT_ID
    ```
@@ -1,5 +1,7 @@
 ---
 name: agent-platform-prompt-management
+metadata:
+  category: AiAndMachineLearning
 description: >-
  Manages and orchestrates prompts in Agent Platform. Use when you need to create,
  list, retrieve, version, or delete managed prompts in Agent Platform. Don't use
@@ -7,6 +9,8 @@ description: >-
  prompts.
 ---

+# Agent Platform Prompt Management
+
 ## Usage Guide

 To use this skill effectively:
@@ -66,16 +70,19 @@ these steps:
 1. **Google Cloud Authentication**: Authenticate with your Google Cloud account
   and configure active Application Default Credentials (ADC) for Agent
   Platform access:
+   
   ```bash
   gcloud auth login
   gcloud auth application-default login
   ```
 2. **Virtual Environment**: Create and activate a dedicated virtual environment:
+   
   ```bash
   python3 -m venv ~/prompt_agent_venv
   source ~/prompt_agent_venv/bin/activate
   ```
 3. **Install Dependencies**: Install the required Agent Platform SDKs:
+   
   ```bash
   pip install google-cloud-aiplatform google-genai
   ```
@@ -1,5 +1,7 @@
 ---
 name: agent-platform-rag-engine-management
+metadata:
+  category: AiAndMachineLearning
 description: >-
  Manage and query Agent Platform RAG Engine Corpora and retrieve grounded
  contexts using the Google GenAI SDK. Use when listing RAG corpora or files,
@@ -50,17 +52,20 @@ the environment is correctly initialized by following these steps:
 1.  **Google Cloud Authentication**: Authenticate with your Google Cloud
    credentials and configure active Application Default Credentials (ADC) for
    Agent Platform access:
+    
    ```bash
    gcloud auth login
    gcloud auth application-default login
    ```
 2.  **Virtual Environment**: Create and activate a dedicated virtual
    environment:
+    
    ```bash
    python3 -m venv ~/rag_agent_venv
    source ~/rag_agent_venv/bin/activate
    ```
 3.  **Install Dependencies**: Install the required Agent Platform SDKs:
+    
    ```bash
    pip install google-cloud-aiplatform google-genai
    ```
@@ -1,5 +1,7 @@
 ---
 name: agent-platform-skill-registry
+metadata:
+  category: AiAndMachineLearning
 description: >
  Interact with the Gemini Enterprise Agent Platform Skill Registry to create
  and search for available skills. Use this skill to enable agents to register
@@ -1,5 +1,7 @@
 ---
 name: agent-platform-tuning-management
+metadata:
+  category: AiAndMachineLearning
 description: >-
  Manages GenAI tuning jobs in Agent Platform. Use this to list, get, or cancel
  ongoing model tuning jobs. Don't use for fine-tuning models (use
@@ -36,6 +38,7 @@ following safety tiers based on the action requested:
 the environment is correctly initialized by following these steps:

 1.  **Virtual Environment**: Create and activate a virtual environment:
+    
    ```bash
    python3 -m venv ~/tuning_mgr_venv
    source ~/tuning_mgr_venv/bin/activate
@@ -43,11 +46,13 @@ the environment is correctly initialized by following these steps:
 2.  **Google Cloud Authentication**: Authenticate with your Google Cloud account
    and configure active Application Default Credentials (ADC) for Agent
    Platform access:
+    
    ```bash
    gcloud auth login
    gcloud auth application-default login
    ```
 3.  **Install Dependencies**: Install the required Agent Platform SDK:
+    
    ```bash
    pip install google-cloud-aiplatform
    ```
@@ -1,5 +1,7 @@
 ---
 name: agent-platform-tuning
+metadata:
+  category: AiAndMachineLearning
 description: >-
  Agent Platform Model Tuning. Use when you need to fine-tune open models
  or Gemini models using Agent Platform infrastructure. Don't use for model
@@ -24,8 +26,8 @@ configuration, monitoring, and deployment.

    -   **No** → **STOP**. Ask the user if they want to tune an Open Model or a
        Gemini Model. **CRITICAL EXCEPTION for Environment Setup Requests:** If
-        the user is specifically asking for environment setup instructions
-        (e.g. "What environment setup is needed?"), you **MUST** provide the full
+        the user is specifically asking for environment setup instructions (e.g.
+        "What environment setup is needed?"), you **MUST** provide the full
        [Phase 0 environment setup](#phase-0) instructions in your initial
        response, *simultaneously* with asking clarifying questions about the
        model category.
@@ -148,13 +150,13 @@ pip install -r references/requirements.txt

 **CRITICAL AGENT INSTRUCTION:** You **MUST** ensure that every Python command or
 script execution (e.g., `python3 scripts/...`, `pip install ...`) is prefixed
-with the virtual environment activation command: `source ~/tuning_agent_venv/bin/activate &&`.
-Additionally, advise the user that every single time they run a Python command,
-execute a script, or inspect data inline, they **MUST** also activate this
-virtual environment first in their bash execution. For example:
-`source ~/tuning_agent_venv/bin/activate && python3 ...`.
-Do not run standalone `python3` commands without activating the environment, as
-they will encounter `ModuleNotFoundError` issues.
+with the virtual environment activation command: `source
+~/tuning_agent_venv/bin/activate &&`. Additionally, advise the user that every
+single time they run a Python command, execute a script, or inspect data inline,
+they **MUST** also activate this virtual environment first in their bash
+execution. For example: `source ~/tuning_agent_venv/bin/activate && python3
+...`. Do not run standalone `python3` commands without activating the
+environment, as they will encounter `ModuleNotFoundError` issues.

 ## Phase 1: Dataset Preparation & Upload {#phase-1}

@@ -254,6 +256,7 @@ confirmation before submitting the job.**

 -   We can calculate a rough estimate of cost of tuning based on the dataset and
    the selected model in the [Models Catalog](references/models.md):
+
    ```bash
    python3 scripts/calculate_cost.py \
        --input my_data.jsonl \
@@ -1,5 +1,7 @@
 ---
 name: alloydb-basics
+metadata:
+  category: Databases
 description: >-
  Manages clusters, instances, and backups for AlloyDB for PostgreSQL, and
  integrates with AlloyDB model context protocol (MCP) tools for automated database operations.
@@ -1,5 +1,7 @@
 ---
 name: bigquery-ai-ml
+metadata:
+  category: AiAndMachineLearning
 description: >-
  Leverages BigQuery's built-in machine learning and GenAI capabilities
  for advanced data analytics. Use when you need to write SQL queries
@@ -1,5 +1,7 @@
 ---
 name: bigquery-basics
+metadata:
+  category: BigDataAndAnalytics
 description: >-
  Manages datasets, tables, and jobs in BigQuery. Use when you need to interact
  with BigQuery, run SQL queries, manage BigQuery resources (datasets, tables,
@@ -1,5 +1,7 @@
 ---
 name: bigtable-basics
+metadata:
+  category: Databases
 description: >-
  Assists in provisioning instances/tables, designing performant schemas, and querying data in Bigtable. Use when designing Bigtable row keys, configuring column families, writing SQL queries or client library code (Java, Go, Python) for Bigtable, or diagnosing performance/hotspotting issues. Also use when provisioning Bigtable clusters using gcloud or cbt CLIs. Don't use for generic Cloud SQL administration.
 ---
@@ -1,5 +1,7 @@
 ---
 name: cloud-run-basics
+metadata:
+  category: Serverless
 description: >-
  Manages Cloud Run services, jobs, and worker pools. Use when you need to deploy applications
  responding to HTTP requests (services), run event-triggered or scheduled tasks (jobs),
@@ -1,5 +1,7 @@
 ---
 name: cloud-sql-basics
+metadata:
+  category: Databases
 description: >-
  This file generates or explains Cloud SQL resources. Use this file when the
  user asks to create a Cloud SQL instance or database for MySQL, PostgreSQL, or
@@ -30,11 +32,13 @@ access to Cloud SQL resources.
 ## Quick Start (PostgreSQL)

 1.  **Enable the API:**
+    
    ```bash
    gcloud services enable sqladmin.googleapis.com --quiet
    ```

 2.  **Create an Instance:**
+    
    ```bash
    gcloud sql instances create INSTANCE_NAME \
      --database-version=POSTGRES_18 \
@@ -48,6 +52,7 @@ access to Cloud SQL resources.

    Because this is a Cloud SQL for PostgreSQL instance, the default admin user
    is `postgres`:
+    
    ```bash
    gcloud sql users set-password postgres \
      --instance=INSTANCE_NAME --password=PASSWORD \
@@ -55,6 +60,7 @@ access to Cloud SQL resources.
    ```

 4.  **Create a database:**
+    
    ```bash
    gcloud sql databases create DATABASE_NAME \
      --instance=INSTANCE_NAME \
@@ -66,6 +72,7 @@ access to Cloud SQL resources.
    You need the instance connection name (which is formatted as
    `PROJECT_ID:REGION:INSTANCE_NAME`) to connect using the Cloud SQL Auth
    Proxy. Retrieve it with the following command:
+    
    ```bash
    gcloud sql instances describe INSTANCE_NAME \
      --format="value(connectionName)" \
@@ -76,11 +83,13 @@ access to Cloud SQL resources.

    The Cloud SQL Auth Proxy must be running to be able to connect to the
    instance. In a separate terminal, start the proxy using the connection name:
+    
    ```bash
    ./cloud-sql-proxy INSTANCE_CONNECTION_NAME
    ```

    With the proxy running, connect using `psql` in another terminal:
+    
    ```bash
    psql "host=127.0.0.1 port=5432 user=postgres dbname=DATABASE_NAME password=PASSWORD sslmode=disable"
    ```
@@ -1,5 +1,7 @@
 ---
 name: firebase-basics
+metadata:
+  category: Serverless
 description: Use this skill whenever you are working on a project that uses Firebase products or services, especially for mobile or web apps.
 ---

@@ -44,7 +46,6 @@ patterns and lack of access to essential reference materials.
    *If the skills are already installed, this command will ensure they are up
    to date. Do not skip this step.*

-
 ## Quick start

 After completing the mandatory prerequisites above, proceed with these steps to
@@ -1,5 +1,7 @@
 ---
 name: gcloud
+metadata:
+  category: DevOps
 description: >-
  Interacts with Google Cloud services using the gcloud CLI safely and
  efficiently. Covers command validation, data reduction, safety guardrails with
@@ -1,5 +1,7 @@
 ---
 name: gemini-agents-api
+metadata:
+  category: AiAndMachineLearning
 description: Manages custom Agent resources on Gemini Enterprise Agent Platform. Use when the user wants to programmatically create, configure, list, update, or delete stateful, server-managed Agent resources (including mounting files, skills, and tools) before executing conversations.
 ---

@@ -32,6 +34,7 @@ export ACCESS_TOKEN=$(gcloud auth print-access-token)
 ### 2. Endpoint URL

 The production Agents Control Plane endpoint is:
+
 ```http
 https://aiplatform.googleapis.com/v1beta1/projects/{PROJECT_ID}/locations/{LOCATION}/agents
 ```
@@ -85,6 +88,7 @@ curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/l
 #### LRO Operations Response

 Since agent provisioning takes a few moments, the endpoint immediately returns an operation tracking object:
+
 ```json
 {
  "name": "projects/1234567890/locations/global/operations/operation-987654321-abcde",
@@ -101,6 +105,7 @@ Since agent provisioning takes a few moments, the endpoint immediately returns a
 #### [Advanced] Mount Skill Registry Resources

 To mount skills directly from the Skill Registry service instead of Cloud Storage, replace the Cloud Storage source item in the payload:
+
 ```json
 "sources": [
  {
@@ -130,6 +135,7 @@ To configure Third-Party MCP servers for an agent, add the server metadata direc
  }
 ]
 ```
+
 *   **name**: A descriptive name for the MCP server.
 *   **url**: The endpoint URL of the external MCP server.
 *   **headers**: (Optional) Custom key-value pairs containing authentication tokens (e.g. API keys, bearer tokens) required to call the server. The platform guarantees that these headers are only sent to the specified MCP server URL.
@@ -165,6 +171,7 @@ curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/1234567890/locat
 #### Finished Success Response

 Once the container is ready, `"done": true` is set, and the completed `Agent` resource description resides inside `"response"`:
+
 ```json
 {
  "name": "projects/1234567890/locations/global/operations/operation-987654321-abcde",
@@ -196,6 +203,7 @@ curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/lo

 #### Response Example
 Returns the complete configured state of the custom Agent resource:
+
 ```json
 {
  "name": "projects/your-project-id/locations/global/agents/my-custom-agent",
@@ -243,6 +251,7 @@ curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/lo

 #### Response Example
 Returns a JSON list of all configured custom Agents under the target project:
+
 ```json
 {
  "agents": [
@@ -300,6 +309,7 @@ curl -X DELETE "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}

 #### Response Example
 A successful deletion request returns an empty JSON response body with HTTP Status `200 OK`:
+
 ```json
 {}
 ```
@@ -314,10 +324,12 @@ Once you have programmatically created and provisioned your custom stateful agen
 > **Interactions Reference**: When explaining or showing how to start conversations with a custom agent, you must always explicitly refer the user to the `gemini-interactions-api` skill for complete conversation and streaming options.

 To interact with your custom agent:
+
 1.  Obtain your agent's resource path name (e.g., `projects/{PROJECT_ID}/locations/global/agents/{AGENT_ID}`).
 2.  Pass this resource path directly inside your data plane conversation requests under the **`agent`** parameter.

 #### Python Example
+
 ```python
 interaction = client.interactions.create(
    agent="projects/your-project-id/locations/global/agents/my-custom-agent",
@@ -326,6 +338,7 @@ interaction = client.interactions.create(
 ```

 #### REST / curl Example
+
 ```json
 {
  "agent": "projects/your-project-id/locations/global/agents/my-custom-agent",
@@ -1,5 +1,7 @@
 ---
 name: gemini-api
+metadata:
+  category: AiAndMachineLearning
 description: Use when the user asks about using Gemini in an enterprise environment or explicitly mentions Vertex AI, Google Cloud, or Agent Platform. Guides the usage of the Gemini API on Agent Platform with the Google Gen AI SDK. Covers SDK usage (Python, JS/TS, Go, Java, C#), capabilities like multimodal inputs, tools, media generation, caching, batch prediction, and Live API.
 compatibility: Requires active Google Cloud credentials and Agent Platform API enabled.
 ---
@@ -60,6 +62,7 @@ Prefer environment variables over hard-coding parameters when creating the clien

 ### Application Default Credentials (ADC)
 Set these variables for standard [Google Cloud authentication](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/start/gcp-auth.md.txt):
+
 ```bash
 export GOOGLE_CLOUD_PROJECT='your-project-id'
 export GOOGLE_CLOUD_LOCATION='global'
@@ -71,6 +74,7 @@ export GOOGLE_GENAI_USE_ENTERPRISE=true

 ### Agent Platform in Express Mode
 Set these variables when using [Express Mode](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/start/api-keys.md.txt) with an API key:
+
 ```bash
 export GOOGLE_API_KEY='your-api-key'
 export GOOGLE_GENAI_USE_ENTERPRISE=true
@@ -78,6 +82,7 @@ export GOOGLE_GENAI_USE_ENTERPRISE=true

 ### Initialization
 Initialize the client without arguments to pick up environment variables:
+
 ```python
 from google import genai

@@ -119,6 +124,7 @@ Use the following models only if explicitly requested:
 ## Quick Start

 ### Python
+
 ```python
 from google import genai

@@ -131,6 +137,7 @@ print(response.text)
 ```

 ### TypeScript/JavaScript
+
 ```typescript
 import { GoogleGenAI } from "@google/genai";
 const ai = new GoogleGenAI({ enterprise: { project: "your-project-id", location: "global" } });
@@ -142,6 +149,7 @@ console.log(response.text);
 ```

 ### Go
+
 ```go
 package main

@@ -173,6 +181,7 @@ func main() {
 ```

 ### Java
+
 ```java
 import com.google.genai.Client;
 import com.google.genai.types.GenerateContentResponse;
@@ -192,6 +201,7 @@ public class GenerateTextFromTextInput {
 ```

 ### C#/.NET
+
 ```csharp
 using Google.GenAI;

@@ -212,6 +222,7 @@ Console.WriteLine(response.Text);
 ## API spec & Documentation (source of truth)

 When implementing or debugging API integration for Agent Platform, refer to the official Agent Platform documentation:
+
 - **Agent Platform Documentation**: https://docs.cloud.google.com/gemini-enterprise-agent-platform/overview.md.txt
 - **REST API Reference**: https://docs.cloud.google.com/gemini-enterprise-agent-platform/reference/rest.md.txt

@@ -1,5 +1,7 @@
 ---
 name: gemini-interactions-api
+metadata:
+  category: AiAndMachineLearning
 description: Guides the usage of Gemini Interactions API on Gemini Enterprise Agent Platform. Use when the user wants to use the stateful, server-managed Interactions API for multi-turn conversations, background execution, streaming, structured output, and function calling on the Agent Platform.
 ---

@@ -24,10 +26,12 @@ The Interactions API is the modern, recommended way to execute Generative AI age
 Before running any code, ensure you are authenticated with Application Default Credentials (ADC) and have the necessary API enabled.

 1.  **Login**:
+    
    ```bash
    gcloud auth application-default login
    ```
 2.  **Enable API** (if not already enabled):
+    
    ```bash
    gcloud services enable aiplatform.googleapis.com
    ```
@@ -49,6 +53,7 @@ export GOOGLE_CLOUD_LOCATION="global"
 ```

 #### Python
+
 ```python
 from google import genai

@@ -57,6 +62,7 @@ client = genai.Client()
 ```

 #### TypeScript/JavaScript
+
 ```typescript
 import { GoogleGenAI } from "@google/genai";

@@ -69,6 +75,7 @@ const ai = new GoogleGenAI();
 Alternatively, pass configuration values directly inside your code:

 #### Python
+
 ```python
 from google import genai
 import google.auth
@@ -78,6 +85,7 @@ client = genai.Client(enterprise=True, project=project_id, location="global")
 ```

 #### TypeScript/JavaScript
+
 ```typescript
 import { GoogleGenAI } from "@google/genai";

@@ -98,6 +106,7 @@ const ai = new GoogleGenAI({
 Submit a single prompt and read the final text response. Under the modern schema, output content is retrieved from the `steps` list.

 #### Python
+
 ```python
 interaction = client.interactions.create(
    model="gemini-3-flash-preview",
@@ -108,6 +117,7 @@ print(interaction.steps[-1].content[0].text)
 ```

 #### TypeScript/JavaScript
+
 ```typescript
 const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
@@ -123,6 +133,7 @@ console.log(interaction.steps[interaction.steps.length - 1].content[0].text);
 Interactions are stateful by default. Store the conversation state in the cloud and reference it in the subsequent turn using `previous_interaction_id`.

 #### Python
+
 ```python
 # Turn 1: Introduce ourselves
 turn1 = client.interactions.create(
@@ -142,6 +153,7 @@ print(f"Turn 2: {turn2.steps[-1].content[0].text}")
 ```

 #### TypeScript/JavaScript
+
 ```typescript
 // Turn 1
 const turn1 = await ai.interactions.create({
@@ -166,6 +178,7 @@ console.log(turn2.steps[turn2.steps.length - 1].content[0].text);
 Stream responses in real-time. Passing `stream=True` returns an iterable chunk generator.

 #### Python
+
 ```python
 response = client.interactions.create(
    model="gemini-3-flash-preview",
@@ -182,6 +195,7 @@ print()
 ```

 #### TypeScript/JavaScript
+
 ```typescript
 const responseStream = await ai.interactions.create({
    model: "gemini-3-flash-preview",
@@ -207,6 +221,7 @@ console.log();
 Retrieve structured, type-safe JSON matching a schema. Under the modern Interactions API, a polymorphic `response_format` argument directly takes the target schema structure.

 #### Python
+
 ```python
 from pydantic import BaseModel, Field

@@ -226,6 +241,7 @@ print(interaction.steps[-1].content[0].text)
 ```

 #### TypeScript/JavaScript
+
 ```typescript
 import { Type } from "@google/genai";

@@ -255,6 +271,7 @@ console.log(interaction.steps[interaction.steps.length - 1].content[0].text);
 Define local tools (functions) and submit execution results to the stateful interaction history.

 #### Python
+
 ```python
 def get_stock_price(ticker: str) -> float:
    """Gets the stock price for a given ticker symbol."""
@@ -287,6 +304,7 @@ if last_step.tool_calls:
 ```

 #### TypeScript/JavaScript
+
 ```typescript
 import { Type } from "@google/genai";

@@ -385,6 +403,7 @@ curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/l

 #### Response Example
 A synchronous POST request returns a JSON object containing the conversation step details and unique identifiers:
+
 ```json
 {
  "id": "your-interaction-id",
@@ -6,6 +6,8 @@ description: >-
  GKE for the first time, or containerizing an app for GKE. Don't use for
  general GKE cluster administration or upgrades (use gke-basics or
  gke-upgrades instead).
+metadata:
+  category: Containers
 ---

 # GKE App Onboarding
@@ -3,6 +3,8 @@ name: gke-backup-dr
 description: >-
  Configures GKE Backup Plans and restore workflows. Use for backup policies,
  disaster recovery, or GKE cluster restores. Don't use for database backups.
+metadata:
+  category: Storage
 ---

 # GKE Backup & Disaster Recovery
@@ -1,5 +1,7 @@
 ---
 name: gke-basics
+metadata:
+  category: Containers
 description: >-
  Core GKE cluster discovery and hub. Use to route to specialized GKE skills.
  Do not use for specialized tasks (networking, security, etc.) directly.
@@ -5,6 +5,8 @@ description: >-
  processing. Use when running GKE batch jobs, configuring GKE HPC, or setting
  up GKE job queues. Don't use for standard web application deployments (use
  gke-app-onboarding instead).
+metadata:
+  category: Containers
 ---

 # GKE Batch & HPC Workloads
@@ -5,6 +5,8 @@ description: >-
  readiness audits. Use when creating GKE clusters, provisioning GKE
  environments, or auditing GKE clusters. Don't use for application
  onboarding or deployment configuration (use gke-app-onboarding instead).
+metadata:
+  category: Containers
 ---

 # GKE Cluster Creation
@@ -2,6 +2,8 @@
 name: gke-compute-classes
 description: >-
  Configures, optimizes, and troubleshoots GKE ComputeClasses. Use when configuring Spot VMs with on-demand fallback, targeting specific accelerators (GPUs/TPUs) or machine families, restricting ComputeClass access, or debugging pending pods related to node pool auto-creation. Do not use for cluster-level Node Auto Provisioning configuration or general GKE cluster creation.
+metadata:
+  category: Containers
 ---

 <!-- disableFinding(LINE_OVER_80) -->
@@ -5,6 +5,8 @@ description: >-
  Use when optimizing GKE costs, rightsizing GKE workloads, or configuring GKE
  Spot VMs. Don't use for general compute class provisioning or GPU Selection
  (use gke-compute-classes instead).
+metadata:
+  category: CloudObservabilityAndMonitoring
 ---

 # GKE Cost Optimization
@@ -6,6 +6,8 @@ description: >-
  verifying GKE production readiness, or checking configurations against
  GKE defaults. Don't use for setting up node autoscaling specifically (use
  gke-scaling instead).
+metadata:
+  category: Containers
 ---

 # GKE Golden Path Configuration
@@ -5,6 +5,8 @@ description: >-
  model servers. Use when deploying GKE inference servers, configuring GKE GPU
  resources for inference, or deploying LLMs on GKE. Don't use for generic
  batch jobs or HPC task queues (use gke-batch-hpc instead).
+metadata:
+  category: Containers
 ---

 # GKE AI/ML Inference
@@ -7,6 +7,8 @@ description: >-
  namespaces, setting up resource quotas, or isolating GKE teams. Don't use
  for single-tenant cluster configuration or general deployment instructions
  (use gke-basics or gke-app-onboarding instead).
+metadata:
+  category: Containers
 ---

 # GKE Multi-Tenancy
@@ -7,6 +7,8 @@ description: >-
  clusters, setting up Gateway API, planning GKE IP ranges, or configuring GKE
  ingress/egress. Don't use for basic application routing that does not
  require dedicated network configuration.
+metadata:
+  category: Networking
 ---

 # GKE Networking
@@ -5,6 +5,8 @@ description: >-
  managed Prometheus. Use when configuring GKE monitoring, setting up GKE logging,
  or configuring Prometheus metrics collection. Don't use to configure local
  application logging frameworks or external APMs outside GKE.
+metadata:
+  category: CloudObservabilityAndMonitoring
 ---

 # GKE Observability
@@ -6,6 +6,8 @@ description: >-
  PDBs, or configuring GKE health probes (liveness, readiness, startup). Don't
  use for disaster recovery setup or full cluster backups (use gke-backup-dr
  instead).
+metadata:
+  category: Containers
 ---

 # GKE Reliability
@@ -5,6 +5,8 @@ description: >-
  (NAP). Use when configuring GKE autoscaling, setting up GKE HPA, setting up
  GKE VPA, or configuring GKE NAP. Don't use for configuring static cluster sizes
  or setting node-level machine styles directly (use gke-compute-classes instead).
+metadata:
+  category: Containers
 ---

 # GKE Workload Scaling
@@ -7,6 +7,8 @@ description: >-
  Security Standards, and IAM roles. Use when securing GKE clusters, setting up
  Workload Identity, hardening RBAC configurations, or configuring GKE secrets.
  Don't use for general network routing configuration (use gke-networking instead).
+metadata:
+  category: Security
 ---

 # GKE Security
@@ -5,6 +5,8 @@ description: >-
  FUSE. Use when configuring GKE storage, creating PVCs, or setting up GCS FUSE
  on GKE. Don't use for database administration or replication strategies
  outside volume provisioning context.
+metadata:
+  category: Storage
 ---

 # GKE Storage
@@ -1,5 +1,7 @@
 ---
 name: gke-upgrades
+metadata:
+  category: Containers
 description: >-
  Plans, executes, and validates Google Kubernetes Engine (GKE) cluster upgrades
  and maintenance operations for both Standard and Autopilot clusters. Produces
@@ -26,6 +28,7 @@ Always frame guidance around the auto-upgrade model: auto-upgrade with maintenan
 ## Context Gathering

 Before producing any upgrade artifact, establish:
+
 - **Cluster mode** — Standard or Autopilot? (Autopilot has no node pool management, mandatory resource requests, no SSH)
 - **Current and target versions** — Node version skew must be within 2 minor versions of control plane.
 - **Release channel** — Rapid, Regular, Stable, or Extended.
@@ -57,6 +60,7 @@ GKE versions follow Kubernetes version terminology: **Major.Minor.Patch** (e.g.,

 ### Support Lifecycle
 Standard GKE versions are supported for 14 months after they become available in the **Regular** channel. This means:
+
 - **Rapid** channel versions may be supported for longer than 14 months (since they enter Rapid before Regular).
 - **Stable** channel versions may be supported for less than 14 months (since they enter Stable after Regular).
 - **Extended** support extends this period up to 24 months. Note that extra cost applies only during the extended support period (months 15-24).
@@ -66,6 +70,7 @@ Standard GKE versions are supported for 14 months after they become available in
 Configure maintenance windows to control auto-upgrade timing. GKE also supports node pool level maintenance exclusions (in addition to cluster level) to block upgrades for specific workloads.

 **Exclusion types & Limits:**
+
 - **"No upgrades" (Scope: `no_upgrades`)**: Blocks all upgrades (minor, patch, node).
  - **Limit**: Max **90 days** of total exclusion duration in any **rolling 365-day window**.
  - **Chaining constraint**: Because of the rolling 365-day limit, you cannot chain multiple exclusions to cover a continuous period longer than 90 days (e.g., you cannot cover a 100-day freeze using `no_upgrades`).
@@ -75,6 +80,7 @@ Configure maintenance windows to control auto-upgrade timing. GKE also supports
  - **Limit**: Up to **180 days per exclusion**. Can be extended up to EoS.

 **Important Exclusion Rules (MUST follow when recommending exclusions and MUST include in the final text response):**
+
 1. **Auto-upgrades only**: Maintenance exclusions **only block automatic upgrades**. Manual upgrades initiated by the user will bypass exclusions. You MUST explain this to the user.
 2. **Warn against "No channel"**: You MUST explicitly warn that disabling release channels ("No channel" / static versioning) is deprecated and must not be used as a replacement for exclusions.
 3. **Compare Scopes**: You MUST explain the difference between 'No upgrades' (limitations, blocks patches) and 'No minor or node upgrades' (allows patches, longer duration). Recommend 'No minor or node upgrades' when the user wants to allow security patches/fixes while blocking minor version jumps.
@@ -87,12 +93,14 @@ Configure maintenance windows to control auto-upgrade timing. GKE also supports
 GKE reserves the right to override user-defined maintenance windows and exclusions for mandatory operations. These overrides cannot be disabled or blocked.

 **Common Override Scenarios:**
+
 - **Critical Security Patches**: Urgent vulnerability fixes that must be applied immediately to protect infrastructure.
 - **End of Support (EoS) / End of Life (EOL) Enforcement**: If a cluster is running an unsupported version, GKE will force upgrade it to a supported version.
 - **Expiring Certificates**: If control plane certificates (CAs) are expiring (within 30 days) and rotation is required to prevent cluster unrecoverability.
 - **Maintenance Starvation**: GKE requires at least 48 hours of maintenance availability in any rolling 32-day window. If exclusions block too much, GKE may force an upgrade.

 **Guidance (MUST follow when overrides are discussed):**
+
 1. **Correlate with Bulletins**: If GKE performs an unexpected upgrade, you MUST explicitly suggest checking GKE Release Notes or Security Bulletins to correlate the event with emergency patches (do not just suggest checking Cloud Audit Logs).
 2. **Design for Resilience**: Workloads must be designed to survive unexpected control plane or node rotation. You MUST recommend:
   - Regional clusters (multi-master) to ensure API availability during control plane upgrades.
@@ -103,6 +111,7 @@ GKE reserves the right to override user-defined maintenance windows and exclusio
 ## Upgrade Planning

 When asked to plan an upgrade, produce a structured document covering:
+
 - Version compatibility (breaking changes, deprecated APIs) (minor version upgrades only)
 - Upgrade path (sequential minor version upgrades) (minor version upgrades only)
 - Node pool upgrade strategy (Standard only)
@@ -110,11 +119,13 @@ When asked to plan an upgrade, produce a structured document covering:
 - Rollback/Contingency procedure (how to revert node pools or coordinate with GKE Support for master rollback)

 **Compatibility Search Rule:**
+
 - If compatibility information (e.g., third-party operator compatibility, GPU driver/CUDA compatibility matrix) is not immediately available in the workspace or via a quick web search, **do NOT loop or make multiple search attempts**. Instead, list the compatibility verification as a **critical pre-upgrade action item** for the user in the checklist.

 ### Node Pool Strategy (Standard Only)

 Recommend **Surge upgrade** as the default and most common strategy, with per-pool settings:
+
 - **Stateless**: Higher `maxSurge` (2-3) for speed, `maxUnavailable=0` for safety.
 - **Stateful/DB**: `maxSurge=1, maxUnavailable=0` (conservative).
 - **GPU (fixed reservation)**: `maxSurge=0, maxUnavailable=1` (no surge capacity).
@@ -152,6 +163,7 @@ Produce checklists as copyable markdown with checkboxes. See [`references/checkl
 **Stateful Workloads:** When stateful workloads (databases) are present, always include checks for PV backup completion and verification of PV reclaim policies (e.g., Retain vs Delete) in the pre-upgrade checklist.

 **Autopilot Checklists:** For Autopilot clusters, ensure the checklists include:
+
 - Verification of `resources.requests` on all containers (Autopilot requirement).
 - You MUST include specific `kubectl` commands for API deprecation checks, specifically: `kubectl get --raw /metrics | grep apiserver_request_total | grep deprecated` to check if any active workloads are using deprecated APIs.
 - Verifying PDBs to ensure they don't block node drain (even though GKE manages nodes, PDBs are still respected).
@@ -165,6 +177,7 @@ Produce step-by-step runbooks with actual `gcloud` and `kubectl` commands. See `
 ## Maintenance Window Pauses

 When diagnosing a \"stuck\" upgrade, consider if it was paused by a maintenance window:
+
 - **Silent Pause Behavior:** If a maintenance window closes before an upgrade (auto or manual) completes, GKE intentionally pauses the rollout to prevent disruption outside allowed times.
 - **Mixed-Version State:** The cluster is left in a stable mixed-version state (some nodes upgraded, some not). You MUST explicitly state that this is a supported and safe intended outcome.
 - **Resumption:** The upgrade will automatically resume when the next maintenance window opens.
@@ -173,6 +186,7 @@ When diagnosing a \"stuck\" upgrade, consider if it was paused by a maintenance
 ## Troubleshooting

 When a user reports a stuck or failing upgrade, you MUST systematically analyze and address ALL 5 potential causes in your final response. Do not omit checks even if you suspect one is the primary cause:
+
 1. **PDB blocking drain:** Identify if any PDB has `ALLOWED DISRUPTIONS = 0` using `kubectl get pdb -A`.
 2. **Resource constraints:** Check if pods are stuck in `Pending` due to capacity limits.
 3. **Bare pods:** Identify pods without owner references that are blocking the drain (recommend deleting them).
@@ -180,6 +194,7 @@ When a user reports a stuck or failing upgrade, you MUST systematically analyze
 5. **PVC attachment issues:** Check for volume attachment failures (especially zone constraints).

 **Stockout / Quota Exhaustion Rule:**
+
 - If the upgrade is stuck due to `ZONE_RESOURCE_POOL_EXHAUSTED` (stockout) or `QUOTA_EXCEEDED` for Compute Engine resources:
  1. Recommend modifying the upgrade strategy to `maxSurge=0` (rolling in-place) to bypass quota limits.
  2. For `QUOTA_EXCEEDED`, suggest requesting a quota increase from Google Cloud.
@@ -1,5 +1,7 @@
 ---
 name: google-cloud-networking-observability
+metadata:
+  category: Compute
 description: >-
  Investigates Google Cloud networking issues by analyzing logs, metrics, and diagnostics. Use when investigating VPC Flow Logs (including cost estimation), NAT, firewall, or threat logs, querying latency and throughput metrics, or running Connectivity Tests for path diagnostics. Don't use for generic VM management or non-observability tasks.
 ---
@@ -66,6 +68,7 @@ description: >-
 ### 2. Schema Verification & Error Recovery

 If a BigQuery query fails with an 'Unrecognized name' error or schema mismatch:
+
 1. **Validate Schema**: Run `bq show --schema --format=json
 {project_id}:{dataset_id}.{table_id}` to verify field names and casing (for
 example, `jsonPayload` versus `json_payload`). 2. **Dry Run**: Before executing
@@ -1,5 +1,7 @@
 ---
 name: google-cloud-recipe-auth
+metadata:
+  category: GettingStarted
 description: Provides expert guidance on authenticating and authorizing to Google Cloud services and APIs, covering human users, service identities, Application Default Credentials (ADC), and best practices for secure access.
 ---

@@ -1,5 +1,7 @@
 ---
 name: google-cloud-recipe-onboarding
+metadata:
+  category: GettingStarted
 description: >-
  Guides a developer's first steps on Google Cloud, covering account creation,
  billing setup, project management, and deploying a first resource.
@@ -45,10 +47,12 @@ For an individual developer, onboarding to Google Cloud involves verifying local
 Before soliciting input or proposing mutations, silently audit the host system's active tooling and environment status.

 1. Check if the `gcloud` CLI binary is installed and accessible:
+   
   ```bash
   which gcloud
   ```
 2. Check if there is an active authenticated identity session:
+   
   ```bash
   gcloud auth list --format="json"
   ```
@@ -62,6 +66,7 @@ Before soliciting input or proposing mutations, silently audit the host system's
 Authorize the gcloud CLI to access Google Cloud using the developer's Google Account, and verify that the account is appropriate for standalone developer onboarding.

 1. **Execute Credentials Authentication:**
+   
   ```bash
   gcloud auth login
   ```
@@ -73,12 +78,14 @@ Authorize the gcloud CLI to access Google Cloud using the developer's Google Acc
   > 3. Do not attempt project creation or resource configuration until authentication is completed successfully.

 2. **Verify Active Identity:**
+   
   ```bash
   gcloud config get-value account --format="json"
   ```

 3. **Programmatic Enterprise Routing Guardrail:**
   Before proceeding, verify if the account is bound to a corporate organization, as enterprise setups must follow a different architecture:
+   
   ```bash
   gcloud organizations list --format="json"
   ```
@@ -96,11 +103,13 @@ Google Cloud resources are organized into **Projects**. When developers sign up

 1. **Silent Project Discovery:**
   List active, accessible projects (limited to prevent context window overflow):
+   
   ```bash
   gcloud projects list --filter="lifecycleState=ACTIVE" --limit=20 --format="json"
   ```
 2. **Reuse Existing Project (Recommended):**
   If the list returns an active project, present it to the developer and propose setting it as the default working project:
+   
   ```bash
   gcloud config set project {PROJECT_ID} --quiet
   ```
@@ -126,10 +135,12 @@ Google Cloud resources are organized into **Projects**. When developers sign up
      - Automatically append a random 4-digit suffix (e.g., changing `my-project` to `my-project-8472`).
      - Propose this new available project ID to the developer and re-solicit consent before retrying.
   - **Execute Project Creation**: Once explicit user consent is confirmed:
+     
     ```bash
     gcloud projects create {PROJECT_ID} --name="{PROJECT_NAME}" --quiet --format="json"
     ```
   - Set the active working project:
+     
     ```bash
     gcloud config set project {PROJECT_ID} --quiet
     ```
@@ -142,17 +153,20 @@ To deploy resources on Google Cloud, your project must be linked to an active Cl

 1. **Audit Billing Status:**
   Check if the active project is already linked to a billing account:
+   
   ```bash
   gcloud billing projects describe {PROJECT_ID} --format="json"
   ```
 2. If the output contains `"billingEnabled": true`, skip linkage and proceed immediately to Section 5: Skill Chaining (Spend Controls & Workloads).
 3. **Discover Available Billing Accounts:**
   If the project is unlinked, query the available billing account handles linked to the authenticated user identity:
+   
   ```bash
   gcloud billing accounts list --format="json"
   ```
 4. **Link Billing Account:**
   Propose linking the project to the discovered Billing Account ID, and execute:
+   
   ```bash
   gcloud billing projects link {PROJECT_ID} --billing-account={BILLING_ACCOUNT_ID} --format="json"
   ```
@@ -183,18 +197,22 @@ Onboarding setup is now complete. To safeguard your environment and deploy workl
 After completing the onboarding steps, programmatically verify the completed environment state using these diagnostic commands:

 1. **Verify CLI Installation:**
+   
   ```bash
   which gcloud
   ```
 2. **Verify Authenticated Identity:**
+   
   ```bash
   gcloud config get-value account
   ```
 3. **Verify Project Workspace Existence:**
+   
   ```bash
   gcloud projects describe {PROJECT_ID} --format="json"
   ```
 4. **Verify Billing Linkage** (Ensure the JSON output contains `"billingEnabled": true`):
+   
   ```bash
   gcloud billing projects describe {PROJECT_ID} --format="json"
   ```
@@ -1,5 +1,7 @@
 ---
 name: google-cloud-waf-cost-optimization
+metadata:
+  category: WellArchitectedFramework
 description: Generates cost optimization guidance for Google Cloud workloads based on the Google Cloud Well-Architected Framework (WAF). Use this skill to evaluate a workload, identify cost requirements and constraints, and provide actionable recommendations for build, deploy, and manage the workload cost-efficiently in Google Cloud.
 ---

@@ -1,5 +1,7 @@
 ---
 name: google-cloud-waf-operational-excellence
+metadata:
+  category: WellArchitectedFramework
 description: >-
  Generates operations-focused guidance for Google Cloud workloads based on the
  design principles and recommendations in the Operational Excellence pillar of
@@ -1,5 +1,7 @@
 ---
 name: google-cloud-waf-performance-optimization
+metadata:
+  category: WellArchitectedFramework
 description: >-
  Generates performance-focused guidance for Google Cloud workloads based on the
  design principles and recommendations in the Performance Optimization pillar
@@ -1,5 +1,7 @@
 ---
 name: google-cloud-waf-reliability
+metadata:
+  category: WellArchitectedFramework
 description: Generates reliability-focused guidance for Google Cloud workloads based on the design principles and recommendations in the Google Cloud Well-Architected Framework. Use this skill to evaluate a workload, identify reliability requirements, and provide actionable recommendations for build, deploy, and manage the workload reliably in Google Cloud.
 ---

@@ -1,5 +1,7 @@
 ---
 name: google-cloud-waf-security
+metadata:
+  category: WellArchitectedFramework
 description: Generates security-focused guidance for Google Cloud workloads based on the design principles and recommendations in the Google Cloud Well-Architected Framework (WAF). Use this skill to evaluate a workload, identify security requirements, and provide actionable recommendations for IAM, network security, data protection, and operational security.
 ---

@@ -1,5 +1,7 @@
 ---
 name: google-cloud-waf-sustainability
+metadata:
+  category: WellArchitectedFramework
 description: >-
  Generates sustainability-focused guidance for Google Cloud workloads based on
  the design principles and recommendations in the Google Cloud Well-Architected
@@ -1,5 +1,7 @@
 ---
 name: iam-recommendations-fetcher
+metadata:
+  category: Identity
 description: >-
  Fetches raw IAM recommendations and associated security insights from Google Cloud for a
  specified target scope (Organization, Folder, or Project). Use when you need to
@@ -1,5 +1,7 @@
 ---
 name: workload-manager-basics
+metadata:
+  category: CloudObservabilityAndMonitoring
 description: >-
  Use this skill to manage Google Cloud Workload Manager evaluations, rules,
  scanned resources, and validation results by using public client libraries