Skip to content
Get packs

Guide · Agent skill

How to use the BigQuery AI & ML agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The bigquery-ai-ml skill gives an AI agent reference guides for BigQuery's built-in machine learning and generative AI SQL functions, such as AI.FORECAST, AI.DETECT_ANOMALIES, AI.KEY_DRIVERS, AI.GENERATE and AI.SEARCH. This guide is for data analysts and developers who have a Google Cloud project with BigQuery and want an agent to write these queries correctly. After reading it you will know how to install the skill, how to phrase requests so the agent uses it, and what to check before running the results.

BigQuery AI & MLgoogle/skills · Apache-2.0

Quick start

  1. 1Download the skill. Download the ZIP for bigquery-ai-ml from this page and unzip it.
  2. 2Place the folder. Move the unzipped folder into ~/.claude/skills/ for all projects, or into your project's .claude/skills/ folder for one project.
  3. 3Or upload in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
  4. 4Confirm your Google Cloud setup. Make sure your project has BigQuery and Vertex AI access and that you hold IAM permissions on the datasets and models you will use.
  5. 5Make a plain-language request. Describe the analysis, naming the table, timestamp column and metric, for example a forecast or an anomaly check.
  6. 6Review the SQL. Read the generated query, check the arguments and run it first on a small sample to control cost.

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 covers BigQuery's built-in ML and GenAI SQL functions. Without it, an agent has to guess function syntax. With it, the agent reads the relevant reference guide and writes SQL using the documented arguments.

The skill's main file is SKILL.md, and it links to one reference file per function. The functions it covers include time-series forecasting, anomaly detection, key driver analysis, semantic search, text classification, similarity, summarization, translation, model evaluation and causal effect measurement.

  • AI.FORECAST: time-series forecasting
  • AI.DETECT_ANOMALIES: outlier and anomaly detection
  • AI.KEY_DRIVERS: finds key drivers of a metric
  • AI.SEARCH: semantic search
  • AI.CLASSIFY: classify text into labels
  • AI.GENERATE: generate text using LLMs
  • AI.CAUSAL_EFFECT: measure the impact of an intervention on a time series

Install the bigquery-ai-ml skill

Download the skill ZIP from the skill's page in this directory and unzip it. To make it available to Claude Code for all your projects, place the unzipped folder in ~/.claude/skills/. To make it available only inside one project, place it in that project's .claude/skills/ folder.

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

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

Check your Google Cloud requirements

The skill only writes and explains SQL. The functions themselves run against your Google Cloud resources, so you need a Google Cloud project with BigQuery and Vertex AI access, and appropriate IAM permissions for the datasets and models you use. If the agent runs gcloud or BigQuery commands directly, it also needs the gcloud CLI or BigQuery access.

Without these, queries will fail or incur cost.

  • A Google Cloud project with BigQuery and Vertex AI access
  • gcloud CLI or BigQuery access, if the agent runs commands itself
  • IAM permissions on the datasets and models you query

Trigger the skill with natural requests

You do not need to name the skill. Describe the analysis you want in plain language and mention BigQuery and your table. The skill's description covers forecasting, anomaly checks, key drivers, semantic or vector search, text classification, similarity, summarization, translation, model evaluation and causal impact.

Name the table, the timestamp column and the metric where you can. The agent needs those to fill in the function arguments correctly.

  • "Forecast daily order revenue for the next 30 days from sales.orders in BigQuery."
  • "Find unusual drops in hourly signups in my analytics.events table."
  • "Write a BigQuery query that groups support tickets into themes using AI.CLASSIFY."
  • "Measure the effect of our March price change on weekly sales using AI.CAUSAL_EFFECT."

Safety notes: scripts and network use

The skill does not run scripts. It does use the network, because the AI functions call Vertex AI models in Google Cloud. Calls cost money and send your data to those models, so check the project and dataset before you ask the agent to run anything.

The skill also asks the agent to read the Usage Attribution guidance before running any gcloud, REST API or MCP command. For commands the agent runs in a terminal, it sets a CLOUDSDK_METRICS_REQUEST_ATTRIBUTION prefix and a User-Agent value naming the skill. These are not added to generated scripts, Terraform or user code.

  • No scripts are run by the skill itself
  • Network use: yes, functions call Vertex AI
  • Review the generated SQL before running it on large tables
CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:bigquery-ai-ml)" gcloud --version

Tips for better results

Give the agent the function's purpose and the data shape. Generative functions return probabilistic output, so treat their results as drafts that need human review, especially when results must be exact or auditable.

For plain table, dataset or job administration, use the separate BigQuery Basics skill instead. This skill excludes general management tasks.

  • Say which column is the timestamp and which is the value to forecast
  • Ask the agent to explain the SQL it wrote before you run it
  • Test on a small date range or sample first
  • Use BigQuery Basics for dataset, table and job administration

What people use it for

  • Forecasting daily or weekly sales, traffic or demand for tables already in BigQuery
  • Detecting unusual spikes or drops in operational metrics with AI.DETECT_ANOMALIES
  • Finding which dimensions drive a change in a metric with AI.KEY_DRIVERS
  • Building semantic search over text stored in BigQuery with AI.SEARCH
  • Classifying support tickets or reviews into themes with AI.CLASSIFY

Frequently asked questions

How do I install the bigquery-ai-ml skill?

Download the skill ZIP from this page and unzip it. Place the folder in ~/.claude/skills/ for all projects or in a project's .claude/skills/ folder for one project. In the Claude apps, you can upload it under Settings → Capabilities → Skills.

What do I need to use it?

You need a Google Cloud project with BigQuery and Vertex AI access, and appropriate IAM permissions for the datasets and models you use. If the agent runs gcloud or BigQuery commands directly, you also need the gcloud CLI or BigQuery access.

Is this skill free?

The skill is licensed under Apache-2.0. The BigQuery and Vertex AI functions run on paid Google Cloud resources, so queries can incur cost. The source does not give pricing, so check Google Cloud's pricing for your usage.

Does the skill run scripts or use the network?

The skill does not run scripts. It does use the network, because the functions call Vertex AI models in Google Cloud.

Can the skill manage my BigQuery datasets and tables?

No. General dataset, table or job administration is excluded. Use the separate BigQuery Basics skill for those tasks.

Are the results of AI.GENERATE and AI.CLASSIFY reliable?

Generative functions produce probabilistic output, so results may vary and need human review. Do not rely on them where results must be exact or auditable.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits data analysts who want forecasts or anomaly checks on tables already in BigQuery, and developers adding semantic search, classification or summarization to BigQuery SQL. It is not a fit for general BigQuery administration, for projects without BigQuery and Vertex AI access, or for workloads that need exact, auditable output, where you should use BigQuery Basics or another approach.

Download the skill