Official agent skill

BigQuery Slot and Cost Optimizer

by google in google/skills

Analyzes BigQuery slot use, query costs and execution bottlenecks from INFORMATION_SCHEMA to diagnose slow queries, slot contention and unpartitioned scans.

OfficialApache-2.0Auto-check passedDatabases

Install BigQuery Slot and Cost Optimizer

skills CLI
$ npx skills add google/skills --skill bigquery-slot-cost-optimizer -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install google/skills bigquery-slot-cost-optimizer --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/google/skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/cloud/bigquery-slot-cost-optimizer .claude/skills/bigquery-slot-cost-optimizer && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
bigquery-slot-cost-optimizer
GitHub stars
21k
Token cost
~2.3k tokens
SKILL.md length
633 words
Files
4 (incl. scripts, references)
Skills in repo
147
Repo updated
First seen
Licence
Apache-2.0

At a glance

Analyzes BigQuery slot use, query costs and execution bottlenecks from INFORMATION_SCHEMA to diagnose slow queries, slot contention and unpartitioned scans.

  • Works in 6 steps: Cloud SDK and client library installation → Project, billing, and regional selection → API enablement → …
  • Diagnosing slow BigQuery queries or slot starvation
  • SKILL.md covers Trigger conditions and intent…, Prerequisites and environment…, Diagnostic execution workflow and Metric interpretation and…, plus 2 more sections
  • Runs Python scripts from its folder; calls python3

What it does

The skill gives an agent a procedure for working out where BigQuery resources go: calculating slot hours, spotting slot contention and queueing, catching Cartesian joins and row-count explosions, and finding scans of unpartitioned tables or missing partition filters. A `scripts/slot_analyzer.py` script does the analysis, with rules and remediation playbooks in two reference files.

Setup matters here. You need the Google Cloud CLI, the `google-cloud-bigquery` Python package, a project with an active billing account and the BigQuery API enabled, Application Default Credentials and the required IAM roles. INFORMATION_SCHEMA views are scoped to a region, so querying the wrong one returns empty job data; pass the matching `--region` and the script normalizes names like `us-central1`. For general BigQuery administration, BigQuery ML or DataFrame work, the skill points to sibling skills.

When your agent uses it

  • Diagnosing slow BigQuery queries or slot starvation
  • Finding the most expensive queries behind high on-demand costs
  • Detecting unpartitioned table scans or join explosions

Example prompts

  • “Find the most expensive BigQuery queries in region-us over the last week.”
  • “Diagnose slot contention in our BigQuery project and suggest fixes.”
  • “Check this query for a Cartesian join and a missing partition filter.”

Requirements

  • Google Cloud CLI with Application Default Credentials
  • Python with the google-cloud-bigquery package
  • A project with billing and the BigQuery API enabled

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

  1. Cloud SDK and client library installation
  2. Project, billing, and regional selection
  3. API enablement
  4. Authentication setup
  5. IAM roles and permissions
  6. Pricing reference

What it can do on your machine

Read from SKILL.md and the folder at commit 5120a76. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • python3

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • docs.cloud.google.com
    • cloud.google.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

BigQuery Slot and Cost Optimizer loads about 2.3k tokens when it runs, and up to ~8.2k if it reads all its reference files. Until then it costs about 110 tokens; SKILL.md has 633 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~110
When it runs · the whole SKILL.md, loaded when a task matches
~2.3k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~8.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from google/skills at commit 5120a76, republished under its Apache-2.0 licence (© google). 633 words, ~2,264 tokens.

Download SKILL.mdSave it as .claude/skills/bigquery-slot-cost-optimizer/SKILL.md (or your agent's skills folder). This skill also uses 3 other files; get the full folder from GitHub.
name
bigquery-slot-cost-optimizer
description
Analyzes Google Cloud BigQuery slot consumption, query costs, and execution bottlenecks using INFORMATION_SCHEMA. Use when diagnosing slow BigQuery queries, slot starvation, high on-demand query costs, unpartitioned table scans, or join performance issues. Don't use for generic BigQuery administration (use bigquery-basics), BigQuery ML (use bigquery-ai-ml), or DataFrame operations (use bigquery-bigframes).
metadata.version
1.0.0
metadata.publisher
google
metadata.category
BigDataAndAnalytics
metadata.tags
bigquery, performance, cost-optimization, slot-analysis, sql

BigQuery slot and cost optimizer

This skill equips AI agents and cloud engineers with procedural heuristics to analyze BigQuery resource consumption, calculate slot hours, identify slot contention and queueing, mitigate Cartesian joins, and optimize unpartitioned table scans.

Trigger conditions and intent mapping

Activate this skill whenever the user asks to:

  • "Optimize BigQuery query performance or reduce slot usage"
  • "Find the most expensive queries in BigQuery"
  • "Diagnose BigQuery slot contention or queueing"
  • "Fix slow running BigQuery jobs or memory spillage"
  • "Detect Cartesian joins or row count explosions in BigQuery"
  • "Identify unpartitioned table scans or missing partition filters"

Prerequisites and environment setup

Before executing this skill, ensure the environment is configured with the necessary SDKs, permissions, and billing:

  1. Cloud SDK and client library installation:

  2. Project, billing, and regional selection:

    • Set the active project:

      bash
      gcloud config set project <PROJECT_ID>
    • Important: the target Google Cloud project must have an active Cloud Billing account attached.

    • Regional selection: specify the target BigQuery dataset location or execution region, as BigQuery INFORMATION_SCHEMA views are strictly region-scoped (for example, multi-regions like region-us or region-eu, or single regions like region-us-central1). Querying the wrong region returns empty job telemetry. Pass the matching region via --region (the script automatically normalizes location names like us-central1 to region-us-central1). For valid location identifiers, see BigQuery locations.

  3. API enablement:

    • Enable the BigQuery API on the project:

      bash
      gcloud services enable bigquery.googleapis.com
  4. Authentication setup:

    • Authenticate the local gcloud environment and configure Application Default Credentials (ADC):

      bash
      gcloud auth login
      gcloud auth application-default login
  5. IAM roles and permissions:

    • The executing principal requires the following minimum IAM roles:
      • roles/bigquery.jobUser: grants permission to run queries and analyze telemetry.
      • roles/bigquery.resourceViewer: grants read-only access to query metadata in INFORMATION_SCHEMA.JOBS_BY_PROJECT and capacity reservations.
  6. Pricing reference:

    • Cost estimates in this skill are for planning purposes. Before running scripts/slot_analyzer.py, retrieve live BigQuery billing rates at runtime from official Google Cloud BigQuery Pricing (and consult BigQuery editions introduction for edition capabilities) after considering user-specific parameters such as target region, chosen edition (Standard, Enterprise, Enterprise Plus), and commitment tier (Pay-as-you-go, 1-year, 3-year). Pass these runtime-fetched rates explicitly via --ondemand-rate <USD_PER_TIB> and --slot-hour-rate <USD_PER_SLOT_HOUR>.

Diagnostic execution workflow

Show full SKILL.md (277 more words)Show less
Execute automated telemetry extraction

Run scripts/slot_analyzer.py to pull and analyze historical query telemetry from INFORMATION_SCHEMA.JOBS_BY_PROJECT, passing the runtime-retrieved pricing rates for your specific region, edition, and commitment tier:

bash
# General analysis passing live regional pricing rates fetched from BigQuery pricing
python3 scripts/slot_analyzer.py --project-id <PROJECT_ID> --days 7 \
  --ondemand-rate <USD_PER_TIB> --slot-hour-rate <USD_PER_SLOT_HOUR> --format table

# Output structured JSON for programmatically parsing recommendations
python3 scripts/slot_analyzer.py --project-id <PROJECT_ID> --days 7 \
  --ondemand-rate <USD_PER_TIB> --slot-hour-rate <USD_PER_SLOT_HOUR> --format json

# Offline verification mode using synthetic or extracted telemetry
python3 scripts/slot_analyzer.py --mock-data-file path/to/extracted_telemetry.json \
  --ondemand-rate <USD_PER_TIB> --slot-hour-rate <USD_PER_SLOT_HOUR> --format table

# Dry-run mode to inspect regional SQL query
python3 scripts/slot_analyzer.py --project-id <PROJECT_ID> --region region-us --dry-run

Run python3 scripts/slot_analyzer.py --help to inspect all supported CLI flags, focus modes (--mode), and required pricing rate arguments (--ondemand-rate per TiB and --slot-hour-rate per slot-hour).

Metric interpretation and decision tree

Evaluate the telemetry output using the following decision rules. CRITICAL MANDATE: After classifying the query issue using the decision tree below, you MUST immediately call view_file on references/remediation_playbooks.md to read and execute the corresponding remediation playbook (Rule SLOT-001, Rule JOIN-001, or Rule PART-001) and include all mandatory diagnostic SQL queries and 4-step checklists in your response.

[Query Telemetry Analyzed]
       |
       +---> If wait_ratio_avg > 0.40 OR slot_contention == TRUE
       |     --> Classify as slot contention and queueing (Rule SLOT-001)
       |     --> MANDATORY: Read Rule SLOT-001 in references/remediation_playbooks.md
       |
       +---> If shuffle_output_bytes_spilled > 0 OR records_written > 10 * records_read
       |     --> Classify as Cartesian join (Rule JOIN-001)
       |     --> MANDATORY: Read Rule JOIN-001 in references/remediation_playbooks.md
       |
       +---> If total_bytes_billed > 10 GB AND no date/partition filters
       |     --> Classify as unpartitioned scan (Rule PART-001)
       |     --> MANDATORY: Read Rule PART-001 in references/remediation_playbooks.md
       |
       +---> Otherwise
             --> Check BI Engine, search indexes, or materialized view opportunities
             --> MANDATORY: Read references/optimization_rules.md

To minimize token consumption in SKILL.md, concrete remediation playbooks (Rule SLOT-001, Rule JOIN-001, Rule PART-001), diagnostic SQL queries, and DDL rewrite patterns are housed in references/:

Verification and validation protocol

Before finalizing query rewrites:

Dry-run validation

Validate query syntax and calculate estimated bytes scanned without incurring cost:

python
from google.cloud import bigquery
client = bigquery.Client()
job_config = bigquery.QueryJobConfig(dry_run=True, use_query_cache=False)
query_job = client.query(optimized_sql, job_config=job_config)
print(f"Scanned bytes: {query_job.total_bytes_processed / (1024**3):.2f} GB")
Offline and dry-run validation
  • Offline mock telemetry verification: validate heuristic classification, slot contention detection, Cartesian join identification, and cost estimation offline using synthetic or extracted JSON telemetry payloads (--mock-data-file):

    bash
    python3 scripts/slot_analyzer.py --mock-data-file path/to/extracted_telemetry.json \
      --ondemand-rate <USD_PER_TIB> --slot-hour-rate <USD_PER_SLOT_HOUR> --format table
  • CLI dry-run inspection: verify regional SQL query formation and script execution without contacting BigQuery or incurring costs:

    bash
    python3 scripts/slot_analyzer.py --project-id <PROJECT_ID> --region region-us --dry-run

© google, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 3 other files (scripts, references) in skills/cloud/bigquery-slot-cost-optimizer of google/skills.

  • SKILL.md
  • references/optimization_rules.md
  • references/remediation_playbooks.md
  • scripts/slot_analyzer.py

Open the folder on GitHubat commit 5120a76

Compare with similar skills

BigQuery Slot and Cost Optimizer next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

BigQuery Slot and Cost Optimizer compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
BigQuery Slot and Cost Optimizer this skillgoogle/skills21k—~2.3kAutomated safety check: PassApache-2.0
Analyze Usageopenshift-eng/ai-helpers120—~2.7kAutomated safety check: PassApache-2.0
Io ConnectorsKilo-Org/kilo-marketplace190—~1.3kAutomated safety check: PassApache-2.0
Altimate Data Warehouse DelegateAltimateAI/data-engineering-skills128—~1.4kAutomated safety check: PassMIT
Expensive Snowflake Query FinderAltimateAI/data-engineering-skills128—~662Automated safety check: PassMIT
Deploying On GCPancoleman/ai-design-components526—~3.9kAutomated safety check: PassMIT

Similar skills

  • Analyze Usage

    openshift-eng/ai-helpers

    A skill your agent uses when analyzing BigQuery usage patterns, costs, and query performance for a GCP project

    120 GitHub stars~2.7k tokensUpdated 2 days ago
    DatabasesAuto-check passed
  • Io Connectors

    Kilo-Org/kilo-marketplace

    Guides development and usage of I/O connectors in Apache Beam.

    190 GitHub stars~1.3k tokensUpdated 10 days ago
    DatabasesAuto-check passed
  • Altimate Data Warehouse Delegate

    AltimateAI/data-engineering-skills

    Delegates dbt and warehouse tasks such as lineage, migrations and cost attribution to the altimate-code CLI agent and relays its answer back.

    128 GitHub stars~1.4k tokensUpdated yesterday
    DatabasesAuto-check passed
  • Expensive Snowflake Query Finder

    AltimateAI/data-engineering-skills

    Ranks the costliest, slowest or heaviest-scanning Snowflake queries from query history and suggests how to optimize them.

    128 GitHub stars~662 tokensUpdated yesterday
    DatabasesAuto-check passed
  • Deploying On GCP

    ancoleman/ai-design-components

    Implement applications using Google Cloud Platform (GCP) services.

    526 GitHub stars~3.9k tokensUpdated 10 mo ago
    DatabasesAuto-check passed
  • Analysis Artifacts

    warpdotdev/oz-skills

    Generate reproducible analysis artifacts — SQL queries, Python visualizations, and summary tables — as you work through a BigQuery data analysis.

    825 GitHub stars~1.1k tokensUpdated 1 mo ago
    DatabasesAuto-check passed

More from google/skills

All 147 skills in this repo
  • Official

    Query Cloud Trace spans, filter by latency thresholds or error status, correlate distributed traces with Cloud Logging, and diagnose latency bottlenecks across Google Cloud services.

    21k GitHub stars~1.7k tokensUpdated today
    Auto-check passed
  • Official

    Manages Google Cloud Privileged Access Manager entitlements and grants: create and edit entitlements, request temporary access, and approve or deny pending grants.

    21k GitHub stars~3.2k tokensUpdated today
    Auto-check passed
  • Official

    Writes Terraform alerting policies for AI agents that emit OpenTelemetry metrics, covering reliability, cost, safety, security and quality signals on Google Cloud.

    21k GitHub stars~4.2k tokensUpdated today
    Auto-check passed
  • Official

    Deploys open models or custom weights from Model Garden to Agent Platform endpoints, checks deployment status and cleans up endpoints, confirming before any change.

    21k GitHub stars~5k tokensUpdated today
    Auto-check passed
  • Official

    Searches, manages and scaffolds skills in the Gemini Enterprise Agent Platform Skill Registry using bundled Python scripts and Google Cloud credentials.

    21k GitHub stars~584 tokensUpdated today
    Auto-check passed
  • Designs GCP infrastructure as local Terraform, validates and scans it against best practices, then imports it to Application Design Center for deployment and troubleshooting.

    21k GitHub stars~4.4k tokensUpdated today
    Auto-check passed

Questions about BigQuery Slot and Cost Optimizer

What does BigQuery Slot and Cost Optimizer do?

Analyzes BigQuery slot use, query costs and execution bottlenecks from INFORMATION_SCHEMA to diagnose slow queries, slot contention and unpartitioned scans. The skill gives an agent a procedure for working out where BigQuery resources go: calculating slot hours, spotting slot contention and queueing, catching Cartesian joins and row-count explosions, and finding scans of unpartitioned tables or missing partition filters.py` script does the analysis, with rules and remediation playbooks in two reference files.

When should I use BigQuery Slot and Cost Optimizer?

BigQuery Slot and Cost Optimizer fits situations like: diagnosing slow BigQuery queries or slot starvation; finding the most expensive queries behind high on-demand costs; detecting unpartitioned table scans or join explosions.

How do I install BigQuery Slot and Cost Optimizer in Claude Code?

Run `npx skills add google/skills --skill bigquery-slot-cost-optimizer -a claude-code`. Or copy the skill folder (skills/cloud/bigquery-slot-cost-optimizer in google/skills) into .claude/skills/bigquery-slot-cost-optimizer in your project. Claude Code loads it when a task matches its description.

How do I install BigQuery Slot and Cost Optimizer in Codex?

Run `npx skills add google/skills --skill bigquery-slot-cost-optimizer -a codex`. Or copy the skill folder (skills/cloud/bigquery-slot-cost-optimizer in google/skills) into .agents/skills/bigquery-slot-cost-optimizer in your project. Codex loads it when a task matches its description.

Can I use BigQuery Slot and Cost Optimizer in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add google/skills --skill bigquery-slot-cost-optimizer -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/bigquery-slot-cost-optimizer, .gemini/skills/bigquery-slot-cost-optimizer, .github/skills/bigquery-slot-cost-optimizer and .opencode/skills/bigquery-slot-cost-optimizer in your project.

What does BigQuery Slot and Cost Optimizer need to run?

Going by SKILL.md and its folder, BigQuery Slot and Cost Optimizer needs Python for the scripts in its folder and the command-line tools its instructions call (python3). Our summary lists: Google Cloud CLI with Application Default Credentials; Python with the google-cloud-bigquery package; A project with billing and the BigQuery API enabled.

Does BigQuery Slot and Cost Optimizer access the network?

SKILL.md names 2 domains. As links in the text: docs.cloud.google.com and cloud.google.com. This is read from the text; nothing was executed.

Is BigQuery Slot and Cost Optimizer safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does BigQuery Slot and Cost Optimizer use?

BigQuery Slot and Cost Optimizer is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does BigQuery Slot and Cost Optimizer use?

About 2.3k tokens (SKILL.md is roughly 9.1k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 5.9k tokens, read only when the agent opens those files.

What are the alternatives to BigQuery Slot and Cost Optimizer?

Skills that share tags, products or a category with BigQuery Slot and Cost Optimizer: Analyze Usage (openshift-eng/ai-helpers, 120 stars), Io Connectors (Kilo-Org/kilo-marketplace, 190 stars), Altimate Data Warehouse Delegate (AltimateAI/data-engineering-skills, 128 stars) and Expensive Snowflake Query Finder (AltimateAI/data-engineering-skills, 128 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains BigQuery Slot and Cost Optimizer?

google (a GitHub organization, an official publisher) maintains it in google/skills, which has 21,069 GitHub stars. The repository holds 147 skills in this directory. The repository was last updated on October 9, 2026.

Source: google/skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.