How to use the BigQuery Observability agent skill

What the skill makes the agent do

Without a skill, an agent asked about a slow BigQuery job has to guess where the data lives and how to query it. This skill gives it a decision order. For a single slow job, the agent starts with a quick CLI or REST lookup. For historical patterns, it writes INFORMATION_SCHEMA SQL. For live alerts and fleet-wide charts, it points you to Cloud Monitoring.

The skill does not diagnose root causes by itself. When the cause is unknown, the description says to hand the problem to the bigquery-troubleshooting skill first. Rewriting business SQL for speed or cost belongs to bigquery-optimization.

• Single job lookup: bq show or the REST API, including performance insights and query plan data.
• Historical analysis: INFORMATION_SCHEMA views such as JOBS and JOBS_TIMELINE.
• Live monitoring: Cloud Monitoring charts for slot utilization and PENDING queue depth.
• Reservation and billing checks: slot capacity timelines, capacity commitments and billable usage.

Install the skill from the download page

You can install the skill in one of three ways. Download the ZIP from the skill's page on this site and unzip it. Then choose the location that fits your setup. 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 instead of a local tool, upload the ZIP under Settings → Capabilities → Skills.

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

Set up Google Cloud before the agent runs anything

The skill expects a working Google Cloud environment. You need the Google Cloud SDK (gcloud) and the bq CLI, an authenticated account or service account, and a project with BigQuery and Cloud Monitoring APIs enabled. A Google Cloud Billing account must be attached to the project. Ask your administrator for IAM roles such as roles/bigquery.jobUser, roles/bigquery.resourceViewer or roles/monitoring.viewer if you do not have them.

The skill's setup steps use these commands. Replace {project_id} with your project ID.

• Use gcloud auth login for CLI and bq commands.
• Use gcloud auth application-default login for SDKs and automated client tools.
• Service accounts can set GOOGLE_APPLICATION_CREDENTIALS to the path of the key file.

Trigger the skill with natural requests

You do not need special syntax. Describe the problem in plain words and name the project or region if you know it. The skill is meant for cases where you already know what kind of telemetry you need: one job's timing, slot contention, reservation capacity or billing usage.

Requests that fit the skill look like the examples below. Vague requests such as 'BigQuery is broken' fit bigquery-troubleshooting better.

• Why did job {job_id} in {project_id} run so slowly? Check its stages.
• Was there slot contention or queueing in the us region last week?
• How much of our reservation capacity was used yesterday, and when did autoscaling max out?
• Audit our on-demand and capacity-based billable usage for the last month.

Know the query rules the agent follows

Every INFORMATION_SCHEMA query must be qualified with a region or a dataset, optionally with a project. Regional views need the region-{region} qualifier, and the query location must match that region. The skill also tells the agent to choose the narrowest permission scope, so it prefers _BY_USER views when you only need your own jobs.

• Regional form: `project`.`region-us`.INFORMATION_SCHEMA.JOBS
• Dataset form: `project`.`analytics`.INFORMATION_SCHEMA.TABLES
• Use _BY_USER views to limit results to queries you ran.

Safety notes: scripts, network and cost

This skill runs scripts and uses the network, because it sends gcloud, bq and API requests to your Google Cloud project. Before a telemetry query runs against a production project, check its cost. The skill's own warning is that INFORMATION_SCHEMA queries can consume slots and cost money. Use the single-job lookup first, because it is cheaper than scanning history.

The skill asks the agent to tag terminal gcloud commands with a usage attribution variable. The tag identifies only the skill and its version. The agent should set it inline on each command rather than with gcloud config set.

• Review the commands the agent proposes before approving them, especially queries on production projects.
• Telemetry queries can consume slots and cost money; prefer narrow time windows.
• Attribution tags are set per command and do not change your gcloud configuration.

Tips for getting useful results

Start with one concrete job or one region and one time window. Narrow questions produce queries that are cheaper to run and easier to read. If the single-job check finds nothing clear, ask the agent to move to system-level views such as JOBS_TIMELINE or RESERVATIONS_TIMELINE, as the skill's workflow describes.

If you also want the optimization and troubleshooting skills, the skill's setup section gives a command that installs the full three-skill suite with npx skills.

• Give the job ID and location when you have them; bq show -j needs both.
• Ask for one question per run so the agent picks one tool and one scope.
• Check the bill-relevant views before and after large analyses.