Skip to content
Get packs

Guide · Agent skill

How to use the BigQuery UDF Builder agent skill

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

The bigquery-udfs skill teaches an AI agent to build custom functions, called User-Defined Functions (UDFs), for Google BigQuery. It is useful if you need custom string, JSON or calculation logic inside BigQuery queries. After this guide you will know how to install the skill, how to ask for help in plain language, and what to check before the agent changes a Google Cloud project.

BigQuery UDF Buildergoogle/skills · Apache-2.0

Quick start

  1. 1Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into the project's .claude/skills/ folder.
  2. 2Install the Google Cloud SDK and log in. Install gcloud and run gcloud auth login so the agent can work with your account.
  3. 3Confirm billing and APIs. Make sure the project has billing enabled and that bigquery.googleapis.com is available, plus the connection and Cloud Run APIs if your function needs them.
  4. 4Describe the function you need. Ask in plain language, including the input type, the output type and what the logic should do.
  5. 5Let the agent choose the UDF type. Review its recommendation, which should favour the lightest option such as a SQL or JavaScript UDF.
  6. 6Review the generated SQL and commands. Check project, dataset, region and any IAM grants before you run anything.
  7. 7Test and troubleshoot. Run the function on sample data in a test dataset, then paste any error message back to the agent for diagnosis.

What the bigquery-udfs skill makes the agent do

An agent skill is a folder of instructions and reference files that an AI agent loads when a task matches its description. This skill covers BigQuery UDFs only. Its main job is to choose the lightest suitable UDF type, which can be SQL, JavaScript, managed Python, or a Remote Function that calls an external endpoint on Cloud Run.

Once the skill is installed, the agent can write the code and SQL that creates the function, list the permissions and APIs it needs, and help troubleshoot errors. It also points to reference guides on aggregate functions, library loading, IAM roles and quotas.

  • Picks a UDF type based on whether it needs a connection and which runtime fits the task
  • Writes CREATE FUNCTION statements, including JavaScript functions that load libraries from gs:// paths
  • Lists the IAM roles and APIs needed, such as bigquery.googleapis.com and bigqueryconnection.googleapis.com
  • Helps diagnose errors and points to reference material on quotas and limits

Install the bigquery-udfs skill

Download the ZIP for this skill from the page you are reading. Unzip it so that the skill folder ends up in one of two places. For a personal setup that works in every project, use ~/.claude/skills/. For a single project, put it in that project's .claude/skills/ folder.

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

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into the project's .claude/skills/ folder
  • Claude apps: Settings → Capabilities → Skills, then upload the skill

Set up Google Cloud before you start

The skill assumes the Google Cloud SDK (gcloud) is installed and you are authenticated. The project needs an active billing account. Install and log in with the command below, then pass the project and region on each command rather than changing global settings.

The skill's own setup enables the APIs it needs. For SQL, JavaScript and offline Python UDFs, that is bigquery.googleapis.com. Calls to APIs from Python and Remote Functions also need bigqueryconnection.googleapis.com, and Remote Functions also need run.googleapis.com. The skill defaults to us-central1 when you do not name a region.

  • Required IAM roles for all UDFs: roles/bigquery.dataEditor on the dataset and roles/bigquery.jobUser on the project
  • For connections: roles/bigquery.connectionAdmin to create them and roles/bigquery.connectionUser for callers
gcloud auth login

Trigger the skill with natural requests

You do not need special syntax. Describe the function you want in plain language and mention BigQuery. The skill's description matches requests about writing custom scalar or aggregate functions, installing PyPI packages or Cloud Storage libraries in a Python or JavaScript UDF, and calling Google Cloud or external APIs from BigQuery.

If you are unsure which type fits, say so. The agent is meant to pick the lightest option that meets the need, so describe the input, the output and where the logic has to run.

  • "Write a BigQuery UDF that normalizes phone numbers to digits with a country prefix."
  • "Create a JavaScript UDF in BigQuery that pulls query keys out of a URL, using a parser from Cloud Storage."
  • "My BigQuery Python UDF calls the Translation API and fails with a permission error. Help me fix the IAM setup."
  • "Should this logic be a SQL UDF or a Remote Function? It needs a Go library."

Choose the right UDF type for your task

The skill recommends the lightest runtime that satisfies the requirement, because native SQL runs inline in BigQuery while external runtimes add overhead. SQL UDFs need no connection and cover regex, struct and array work, and aggregates. JavaScript UDFs run in a V8 sandbox and suit string or JSON logic. Managed Python UDFs use Python 3.11 and run offline unless you add a connection. Remote Functions handle non-Python runtimes, private VPC access, GPUs or custom Cloud Run scaling.

  • SQL UDF: default choice, no connection needed
  • JavaScript UDF: custom string or JSON logic, optional .js libraries from Cloud Storage
  • Managed Python UDF (offline): pure compute with PyPI packages, no connection needed
  • Managed Python UDF with WITH CONNECTION: Python code that calls Google Cloud APIs
  • Remote Function (REMOTE WITH CONNECTION): external services in Go, Java or Node.js, or other needs Python cannot meet

Review the code before running it

Every function the agent writes is a SQL statement that changes your project. A persistent function is created in a dataset, and a connection or IAM grant can change who is allowed to call external services. Read the CREATE statement, check the dataset and project names, and run it in a test dataset first.

The skill's safety notes say the agent may generate IAM grants and API enablement commands that change real cloud projects and can incur billing. Treat those as proposals to review, not commands to run without thought.

  • Check the project ID, dataset and region in every generated command
  • Confirm IAM grants are the least privilege needed
  • Test in a non-production dataset before deploying
  • Expect possible billing when APIs or external calls are used

What people use it for

  • Normalizing messy phone numbers or codes with a SQL UDF using regular expressions
  • Extracting keys from URLs or JSON strings with a JavaScript UDF that loads a parser from Cloud Storage
  • Running vectorized Python calculations with pandas or PyArrow inside a persistent managed Python UDF
  • Calling a Google Cloud API from a Python UDF that uses a BigQuery connection
  • Wrapping a Go or Node.js service behind a Cloud Run endpoint as a Remote Function

Frequently asked questions

Is the bigquery-udfs skill free?

The skill is published under the Apache-2.0 licence in the google/skills repository. Using BigQuery and the other Google Cloud services it configures can incur billing, and the skill's own notes warn about that.

What do I need before installing the bigquery-udfs skill?

You need the Google Cloud SDK (gcloud) installed and authenticated, an active Google Cloud project with billing enabled, and the BigQuery APIs enabled. Calls to external APIs also need the BigQuery Connection API, and Remote Functions need Cloud Run.

Where do I put the skill so Claude can use it?

Unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.

What is the difference between a SQL UDF and a JavaScript UDF?

A SQL UDF is the default and needs no connection, and the skill says it has the lowest latency. A JavaScript UDF runs in a V8 sandbox and suits custom string or JSON logic, and it can load .js libraries from Cloud Storage.

Can the bigquery-udfs skill handle table and dataset management?

No. The skill says standard table and dataset work belongs to the bigquery-basics skill, and BigQuery ML models and DataFrame workflows belong to other skills.

Why did my BigQuery Python UDF fail with an IndentationError?

Top-level Python statements inside the AS r'''...''' block must start at the left margin. Indenting imports or function definitions to match the SQL causes this error, so ask the agent to remove the leading indentation.

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

Use this skill if you write BigQuery UDFs and want an agent to choose the lightest function type, write the SQL and explain the permissions. Pick something else if you only need table or dataset administration, or if you cannot review the IAM and billing changes an agent may propose before they touch a production project.

Download the skill