docs(skills): refresh SKILL.md frontmatter for routing clarity (sensei audit)

skills/cloud/alloydb-basics/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: alloydb-basics
-description: >-
-  Manages clusters, instances, and backups for AlloyDB for PostgreSQL, and
-  integrates with AlloyDB model context protocol (MCP) tools for automated database operations.
+description: "**WORKFLOW SKILL** — Create and manage AlloyDB for PostgreSQL clusters, instances, and backups, including AlloyDB AI features (vector and hybrid search, NL, forecasting, model endpoint management). WHEN: \"create AlloyDB cluster\", \"AlloyDB instance\", \"PostgreSQL on Google Cloud\", \"AlloyDB AI\", \"vector search AlloyDB\", \"AlloyDB Terraform\", \"AlloyDB MCP\". INVOKES: AlloyDB MCP server, gcloud CLI, Developer Knowledge MCP."
 ---
 
 # AlloyDB Basics

skills/cloud/bigquery-basics/SKILL.md

@@ -1,12 +1,6 @@
 ---
 name: bigquery-basics
-description: >-
-  Manages datasets, tables, and jobs in BigQuery, and integrates with BigQuery
-  ML and Gemini for advanced data analytics and AI-driven insights. Use when
-  you need to interact with BigQuery, run SQL queries, manage BigQuery
-  resources, or leverage BigQuery's built-in ML capabilities. Also use when
-  performing data analysis, ingesting data into BigQuery, or developing AI
-  applications on BigQuery.
+description: "**WORKFLOW SKILL** — Manage datasets, tables, and jobs in BigQuery; run SQL; integrate with BigQuery ML and Gemini for analytics and AI-driven insights. WHEN: \"BigQuery query\", \"BigQuery ML\", \"create dataset\", \"BigQuery table\", \"data warehouse Google Cloud\", \"BigQuery MCP\", \"BigQuery Gemini\". INVOKES: BigQuery MCP server, bq CLI, Gemini CLI extension."
 ---
 
 # BigQuery Basics

skills/cloud/cloud-run-basics/SKILL.md

@@ -1,9 +1,6 @@
 ---
 name: cloud-run-basics
-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),
-  or handle always-on pull-based background processing (worker pools).
+description: "**WORKFLOW SKILL** — Deploy Cloud Run services (HTTP), jobs (scheduled/event), and worker pools (always-on pull-based) on Google Cloud's managed container platform. WHEN: \"deploy Cloud Run\", \"Cloud Run service\", \"Cloud Run job\", \"Cloud Run worker pool\", \"serverless container Google Cloud\", \"Cloud Run from source\", \"Cloud Run MCP\". INVOKES: Cloud Run MCP server, gcloud CLI, Cloud Build."
 ---
 
 # Cloud Run Basics

skills/cloud/cloud-sql-basics/SKILL.md

@@ -1,17 +1,6 @@
 ---
 name: cloud-sql-basics
-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
-  SQL Server.
-
-  Cloud SQL manages third-party MySQL, PostgreSQL, and SQL Server instances as
-  resources in Cloud SQL. For example, when Cloud SQL creates an open-source
-  MySQL instance, the resulting resource is a Cloud SQL for MySQL instance that
-  Google Cloud manages.
-
-  Cloud SQL handles backups, high availability, and secure connectivity for
-  relational database workloads.
+description: "**WORKFLOW SKILL** — Create and manage Cloud SQL instances and databases for MySQL, PostgreSQL, and SQL Server, including HA, backups, and Auth Proxy connectivity. WHEN: \"create Cloud SQL instance\", \"Cloud SQL PostgreSQL\", \"Cloud SQL MySQL\", \"Cloud SQL SQL Server\", \"Cloud SQL Auth Proxy\", \"Cloud SQL Terraform\", \"Cloud SQL MCP\". INVOKES: Cloud SQL MCP server, gcloud CLI, Cloud SQL Auth Proxy."
 ---
 
 # Cloud SQL Basics

skills/cloud/firebase-basics/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: firebase-basics
-description: Use this skill whenever you are working on a project that uses Firebase products or services, especially for mobile or web apps.
+description: "**WORKFLOW SKILL** — Build and deploy Firebase mobile and web apps, including Auth, Firestore, Hosting, Functions, and the Firebase MCP server. WHEN: \"Firebase project\", \"Firebase Hosting\", \"Firestore\", \"Firebase Auth\", \"Firebase Functions\", \"firebase deploy\", \"Firebase MCP\". INVOKES: firebase-tools CLI, Firebase MCP server, npx commands."
 ---
 
 # Firebase Basics

skills/cloud/gemini-api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gemini-api
-description: Guides the usage of the Gemini API on Agent Platform with the Google Gen AI SDK. Use when the user asks about using Gemini in an enterprise environment or explicitly mentions Vertex AI, Google Cloud, or Agent Platform. Covers SDK usage (Python, JS/TS, Go, Java, C#), capabilities like Live API, tools, multimedia generation, caching, and batch prediction.
+description: "**UTILITY SKILL** — Use the Gemini API on Agent Platform (formerly Vertex AI) via the Google Gen AI SDK for text, multimodal, embeddings, function calling, Live API, and batch prediction. WHEN: \"Gemini API\", \"Vertex AI Gemini\", \"Agent Platform Gemini\", \"Gen AI SDK\", \"google-genai\", \"Gemini Live API\", \"Gemini batch prediction\". INVOKES: google-genai SDK, gcloud auth."
 compatibility: Requires active Google Cloud credentials and Agent Platform API enabled.
 ---
 

skills/cloud/gke-basics/SKILL.md

@@ -4,7 +4,7 @@ license: Apache-2.0
 metadata:
   author: Google Cloud
   version: "1.0.0"
-description: "Plan, create, and configure production-ready Google Kubernetes Engine (GKE) clusters using the golden path Autopilot configuration. Covers Day-0 checklist, Autopilot vs Standard, networking (private clusters, VPC-native, Gateway API), security (Workload Identity, Secret Manager, RBAC hardening), observability, scaling, cost optimization, and AI/ML inference. WHEN: create GKE cluster, provision GKE environment, design GKE networking, secure GKE, optimize GKE cost, GKE autoscaling, GKE inference, GKE upgrade, GKE observability, GKE multi-tenancy, GKE batch, GKE HPC, GKE compute class."
+description: "**WORKFLOW SKILL** — Plan, create, and configure production-ready GKE clusters using the golden-path Autopilot configuration; covers networking, security, scaling, cost, upgrades, and AI/ML inference. WHEN: \"create GKE cluster\", \"GKE Autopilot\", \"GKE networking\", \"Workload Identity\", \"GKE autoscaling\", \"GKE inference\", \"GKE upgrade\". INVOKES: gcloud, kubectl, GKE MCP server."
 ---
 
 # Google Kubernetes Engine (GKE) Basics

skills/cloud/google-cloud-networking-observability/SKILL.md

@@ -1,7 +1,6 @@
 ---
-name: google-cloud-recipe-networking-observability
-description: >-
-  Investigates Google Cloud networking issues by analyzing logs, metrics, and diagnostics. Use when investigating VPC Flow Logs, NAT, firewall, or threat logs, querying latency and throughput metrics, or running Connectivity Tests for path diagnostics.
+name: google-cloud-networking-observability
+description: "**ANALYSIS SKILL** — Investigate Google Cloud networking issues by analyzing VPC Flow Logs, firewall logs, Cloud NAT logs, threat logs, metrics, and Connectivity Tests. WHEN: \"VPC Flow Logs\", \"Cloud NAT logs\", \"firewall logs Google Cloud\", \"Cloud Armor threat\", \"network latency Google Cloud\", \"Connectivity Test\", \"BigQuery network logs\". INVOKES: Cloud Monitoring MCP, BigQuery MCP, Cloud Logging MCP, gcloud CLI, bq."
 ---
 
 # Google Cloud Networking Observability Expert

skills/cloud/google-cloud-recipe-auth/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: google-cloud-recipe-auth
-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.
+description: "**ANALYSIS SKILL** — Guide authentication and authorization to Google Cloud services, covering ADC, service accounts, Workload Identity Federation, IAP, OIDC tokens, and IAM. WHEN: \"gcloud auth\", \"Application Default Credentials\", \"Workload Identity Federation\", \"service account impersonation\", \"OIDC token\", \"IAM role\", \"GCP authentication\". INVOKES: gcloud auth, IAM Service Account Credentials API."
 ---
 
 # Authenticating to Google Cloud

skills/cloud/google-cloud-recipe-onboarding/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: google-cloud-recipe-onboarding
-description: Guidance for a developer's first steps on Google Cloud, covering account creation, billing setup, project management, and deploying a first resource.
+description: "**WORKFLOW SKILL** — Onboard a developer to Google Cloud: account setup, billing, first project, gcloud CLI install, enabling APIs, and deploying a first resource. WHEN: \"Google Cloud onboarding\", \"new GCP project\", \"gcloud init\", \"GCP free trial\", \"first Cloud Run\", \"enable Google Cloud API\", \"GCP billing setup\". INVOKES: gcloud CLI, Google Cloud Console."
 ---
 
 # Onboarding to Google Cloud

skills/cloud/google-cloud-waf-cost-optimization/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: google-cloud-waf-cost-optimization
-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.
+description: "**ANALYSIS SKILL** — Evaluate Google Cloud workloads against the Cost Optimization pillar of the Well-Architected Framework; recommend FinOps practices, rightsizing, CUDs, and storage lifecycle policies. WHEN: \"Google Cloud cost optimization\", \"FinOps Google Cloud\", \"Committed Use Discount\", \"GCP rightsizing\", \"GCP cost review\", \"WAF cost\", \"Cloud Hub Optimization\". INVOKES: Active Assist Recommender, BigQuery billing export, Cloud Billing reports."
 ---
 
 # Google Cloud Well-Architected Framework skill for the Cost Optimization pillar

skills/cloud/google-cloud-waf-reliability/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: google-cloud-waf-reliability
-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.
+description: "**ANALYSIS SKILL** — Evaluate Google Cloud workloads against the Reliability pillar of the Well-Architected Framework; recommend SLOs, redundancy, autoscaling, graceful degradation, and DR practices. WHEN: \"Google Cloud reliability\", \"GCP SLO\", \"GCP high availability\", \"GCP autoscaling\", \"WAF reliability\", \"GCP disaster recovery\", \"chaos engineering GCP\". INVOKES: Cloud Monitoring, Backup and DR Service."
 ---
 
 # Google Cloud Well-Architected Framework skill for the Reliability pillar

skills/cloud/google-cloud-waf-security/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: google-cloud-waf-security
-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.
+description: "**ANALYSIS SKILL** — Evaluate Google Cloud workloads against the Security pillar of the Well-Architected Framework; recommend zero-trust, shift-left, IAM hardening, supply-chain controls, and secure AI practices. WHEN: \"Google Cloud security\", \"GCP zero trust\", \"VPC Service Controls\", \"Binary Authorization\", \"Cloud Armor\", \"WAF security\", \"GCP shift left\". INVOKES: Security Command Center, Google SecOps, IAM, VPC Service Controls."
 ---
 
 # Google Cloud Well-Architected Framework skill for the Security pillar