How to use the BigQuery Troubleshooting agent skill

What is an agent skill and what does this one do?

An agent skill is a folder of instructions and reference files that an AI agent loads when a task matches the skill's description. This one, bigquery-troubleshooting, is published under the Apache-2.0 licence in the google/skills repository.

Once installed, the agent follows structured procedures for investigating BigQuery problems. It covers slow or failing jobs, stage bottlenecks in query execution graphs, cluster capacity contention, and cost spikes from on-demand queries, slot autoscaling, or storage growth. It starts with a bounded high-level scan, summarizes what it found, and offers focused drill-down options instead of running many queries at once.

The skill is a diagnostic playbook, not a SQL writing tool. It does not write or optimize your queries and does not plan capacity in advance. Those tasks belong to the companion skill bigquery-optimization.

Install the BigQuery Troubleshooting skill

Download the ZIP of the skill from this page and unzip it. You can install it in one of two places. For a personal setup, unzip it into ~/.claude/skills/. For a single project, unzip it into the .claude/skills/ folder inside that project.

If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

The skill includes a SKILL.md file and reference files for each diagnostic area, so the folder should contain SKILL.md and a references folder after unzipping.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills (upload the ZIP)

Set up Google Cloud before you start

The diagnostics need live telemetry from your Google Cloud project, so the environment must be ready. The skill's setup steps tell the agent to set the active project, enable the APIs, and authenticate. You can run these yourself first.

Authentication depends on what you use. Command-line checks use gcloud auth login, while SDKs and automated diagnostic scripts use gcloud auth application-default login. Service accounts can instead set GOOGLE_APPLICATION_CREDENTIALS to the path of a key file.

• Google Cloud SDK (gcloud) installed and configured
• BigQuery and Cloud Monitoring APIs enabled in the project
• An active Google Cloud Billing account attached to the project
• IAM roles such as roles/bigquery.jobUser, roles/bigquery.resourceViewer, roles/monitoring.viewer and roles/billing.viewer

Ask for help with natural requests

You do not need to name the skill or any command. Describe the symptom and include what you know, such as the project, region, reservation or job ID. The skill is designed for open-ended questions too, so a vague question like why BigQuery is slow today is enough to start.

Expect the agent to first run a bounded baseline scan, then report what it found and suggest two or three focused next steps. For performance problems it compares a slow run against a fast one, looking at data processed, system contention and configuration changes. For cost problems it looks at on-demand TiB, capacity slot-hours and storage GiB.

• Why did my nightly BigQuery jobs slow down this week?
• Our Google Cloud bill spiked last month. Find out whether queries, slots or storage caused it.
• Job bqjob_123 in region us is failing. Find the stage that is the bottleneck.
• Our reservation looks saturated. Check whether slot contention is the cause.

Examples of what the agent investigates

The reference files cover distinct problems, and the agent picks the matching one based on your symptom. Performance work covers resource contention, slot saturation and configuration changes. Cost work covers on-demand query spend, capacity slot usage and storage growth.

Each investigation ends with a summary and remediation options such as partition filter enforcement, query caps, commitment purchases or reduced Time Travel, depending on what the evidence shows.

• Single-job stage bottlenecks such as slot contention or spill to disk
• Runaway on-demand queries that scan large amounts of data
• Autoscaling slot bursts and uncovered baseline slots
• Storage growth from Time Travel and Fail-Safe retention

Safety notes: scripts and network access

This skill runs scripts and uses the network. Its diagnostics call Google Cloud APIs with your credentials, so the agent can read job, reservation, monitoring and billing data in your project. Only install it if you are comfortable with that access.

The skill asks the agent to tag its gcloud commands with a usage attribution variable, set inline on each command rather than saved with gcloud config set. Review the IAM roles you grant, because roles such as those for cost and job data expose sensitive information.

• Runs scripts: yes
• Uses network: yes
• Use least-privilege IAM roles where you can

Tips for better results

Give the agent the project ID, region and any reservation or job ID up front. The more precise the scope, the smaller the initial scan. If you only want a ready-made monitoring query, ask for the bigquery-observability skill instead, since this skill does not focus on that.

• Name the time window when you know it, such as the last seven days versus the previous week.
• Install the companion skills bigquery-observability and bigquery-optimization if you want query templates or SQL help.
• Expect a summary before deep dives; reply with the drill-down option you want.