How to use the BigQuery Cost & Performance Optimization agent skill

What does the skill make the agent do?

Once installed, the agent follows workflows for optimizing a BigQuery environment. It can help you decide whether to move workloads from on-demand pricing to Editions and how to size reservations. It can compare physical and logical storage billing, design partitioning and clustering using ready-made DDL templates, and set table and dataset expiration rules. It also evaluates search indexes, materialized views and BI Engine, and suggests SQL query rewrites.

Where a built-in Google recommendation tool exists, the agent points you to it and walks you through the steps, such as opening the Slot Estimator tab.

• Editions migration and reservation rightsizing
• Physical vs. logical storage billing evaluation
• Partitioning, clustering and table DDL templates
• Partition, table and dataset expiration rules
• Search indexes, materialized views and BI Engine
• SQL query improvements to reduce slot-time and data read

How do you install the skill?

There are two routes. In either case you download the skill ZIP from this page and unzip it.

For Claude Code, unzip the folder into your personal skills directory ~/.claude/skills/, or into a project's .claude/skills/ directory to limit it to that project.

For the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

Install the companion skills

The skill is part of a three-skill operations suite with bigquery-observability and bigquery-troubleshooting. If a companion skill is missing, the source recommends installing the full suite with npx skills add. The optimization skill still works without bigquery-observability, because its reference guides include self-contained baseline formulas and query templates.

What do you need before you start?

The skill runs commands against your Google Cloud project, so set up the environment first. Set the active project, enable the BigQuery and BigQuery Reservation APIs, and authenticate. Interactive use needs gcloud auth login, while SDKs and automation use application-default credentials.

• Google Cloud SDK (gcloud) installed and configured
• An active Google Cloud project with billing enabled
• BigQuery and BigQuery Reservation APIs enabled
• gcloud auth login or application-default credentials
• IAM roles such as bigquery.admin, bigquery.resourceAdmin, dataEditor or jobUser, depending on the task

How do you trigger the skill with a natural request?

You do not need special syntax. Describe the goal and the dataset or project, and the agent will match the request to the right workflow. Requests about cost, editions, reservations, storage billing, partitioning, clustering, expiration, search indexes, materialized views, BI Engine or slow SQL are all in scope.

Ask for a specific target where you can. If you do not name a region, the skill falls back to the US multi-region and states that assumption at the top of its answer.

• Should we move our BigQuery workloads from on-demand to Editions? Size the reservation.
• Would physical storage billing be cheaper for the sales dataset in europe-west1?
• Write partitioning and clustering DDL for the events table and enforce a partition filter.
• Which of these tables should get a materialized view for our dashboard queries?
• Rewrite this query to read less data.

What does a typical session look like?

The agent first states the project_id and region it is scoping to. It then reads the relevant reference guide, runs or proposes queries, and presents recommendations. Some steps are only guidance: for Editions and reservations, you follow the Slot Estimator steps yourself in the console, selecting On-Demand as the source, then reviewing the Cost-Optimized Recommendations and Slot Usage Chart.

Expect the agent to phrase its findings as improving cost-efficiency or optimizing your bill, not as guaranteed savings.

What are the safety notes?

This skill runs scripts and uses the network. It executes gcloud commands and can generate DDL that modifies tables. DDL can change partitioning and clustering, and expiration settings can delete data. Review every statement before you run it, and test on a non-production copy where possible.

The skill is not for production changes without review. It is also not the right tool for diagnosing why one specific job failed or ran slowly; the skill sends that work to bigquery-troubleshooting. It only covers Google Cloud BigQuery, not other warehouses.

• Review DDL and expiration rules before applying them to production
• Changing billing models or schemas can affect costs and data
• Use bigquery-troubleshooting for failed or slow individual jobs
• Guidance applies to BigQuery only

Tips for getting better results

Give the agent real numbers where you have them, such as dataset size, query volume and dashboard frequency, because the recommendations depend on them. Ask it to show the verification query so you can check the result yourself. For storage billing, note that a query returning zero rows can mean a region mismatch or no native tables, not zero billable usage.

• Name the dataset and region in the request
• Ask for the verification step alongside any DDL
• Check that the region in the result matches your dataset location