Agent skill · google
bigquery-troubleshooting
Provides diagnostic workflows and step-by-step root-cause analysis procedures for actively broken, failing, or slow BigQuery jobs, execution graph and query plan stage bottlenecks, system performance issues, or unexpectedly expensive workloads. Use when interpreting symptoms, isolating bottlenecks, diagnosing cost spikes (on-demand query spend, capacity slot autoscaling, storage growth), execution graph stages or substep variables, identifying root causes, and determining remediation steps. Don't use for writing or optimizing SQL, proactive capacity planning, or storage layout design (use bigquery-optimization), or when the user already knows which telemetry they want and just needs the query (use bigquery-observability).
What it needs
About 5k tokens when loaded.
What this skill does
BigQuery Troubleshooting Attribution MUST READ: Before executing any gcloud, REST API, or MCP command, you MUST read Usage Attribution. For commands executed directly in the terminal (never in generated scripts, Terraform, or user code), prefix gcloud with CLOUDSDKMETRICSREQUESTATTRIBUTION="agent-skills/1.0 (skill:bigquery-troubleshooting)" and append agent-skills/1.0 (skill:bigquery-troubleshooting) to User-Agent headers. Prerequisites & Environment Setup Before running diagnostic queries or investigating incident telemetry: 1. Google Cloud SDK: Ensure the Google Cloud SDK is installed and configured. 2. Project Selection: Set the active Google Cloud project: 3. API Enablement: Ensure BigQuery and Cloud Monitoring APIs are enabled: 4. Authentication: Authenticate the environment: CLI commands (bq show -j): gcloud auth login SDKs and automated diagnostic scripts: gcloud auth application-default login Service accounts: Set GOOGLEAPPLICATIONCREDENTIALS="/path/to/key.json" 5. Billing & IAM Roles: Verify an active Google Cloud Billing account is attached to {projectid}. Ensure appropriate IAM roles: roles/bigquery.jobUser: Executing diagnostic queries. roles/bigquery.resourceViewer or roles/bigquery.admin: Inspecting reservation and job execution telemetry. roles/monitoring.viewer: Cloud Monitoring metrics. roles/billing.viewer: Cloud Billing reports and cost attribution. 6. Companion Skills Installation: This skill is part of a 3-pillar operations suite (bigquery-observability, bigquery-optimization, bigquery-troubleshooting). If any companion skill is not yet installed in your environment, install the full suite: (If bigquery-observability is not installed, use the self-contained baseline formulas and query templates provided directly in the reference sections below). Workflow 1. Scope & Symptom Identification: Identify the primary symptom, target projectid, region, reservationid, or jobid, and domain (Performance, Compute Cost, or Storage Cost). …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills google/bigquery-troubleshooting