How to use the Retail Product Search agent skill

What an agent skill is and what this one does

An agent skill is a folder containing a SKILL.md file and supporting scripts and reference documents. When you ask a compatible AI agent for a matching task, the agent reads the skill and follows its instructions.

This skill creates product search agents with semantic search and retrieval-augmented generation (RAG) on Google Cloud. It handles the full pipeline: ingesting catalog data into BigQuery, setting up a Vector Search collection, scaffolding an ADK agent, running evaluation, and deploying to Cloud Run.

• Loads a catalog: a bundled 5-product demo CSV or your own file (local path or gs:// location).
• Creates a Vector Search collection for meaning-based product lookup.
• Scaffolds a reference ADK agent with a retrieval tool.
• Prepares evaluation and Cloud Run deployment.

Install the skill on macOS, Linux or Windows

Download the skill ZIP from this page and unzip it into one of two locations. For a personal install available in all projects, unzip into ~/.claude/skills/. For a single project, unzip into that project's .claude/skills/ folder.

Alternatively, in the Claude apps, open Settings → Capabilities → Skills and upload the ZIP there.

The companion skills must also be installed. The skill recommends this command when they are missing: npx skills add google/skills --skill bigquery-basics gemini-api. This requires Node with npx.

Check the requirements before you start

You need Python 3.11 or newer, a Google Cloud project with billing enabled, and gcloud CLI access. BigQuery and Vector Search (Gemini Enterprise Agent Platform) must be enabled in the project. The skill's own setup uses us-central1, which the source describes as the only confirmed-working region for Vector Search 2.0.

• Python 3.11 or newer
• Google Cloud project with billing
• gcloud CLI access
• BigQuery and Vector Search enabled
• Node/npx for the companion skill install

Trigger the skill with a natural request

Ask your agent in plain language. The skill's description lists phrases that match it, such as build a product search agent, create an e-commerce search, make a shopping assistant, set up semantic catalog discovery, ingest products into Vector Search, or deploy a retail RAG agent.

The skill then opens with a setup mode choice. Quick start asks two questions and takes defaults for the rest. Full setup asks four, adding product fields level and GCP region. Quick start is intended for demos and first-timers; Full setup is intended for real builds.

• "Build a product search agent for my shop catalog."
• "Make a shopping assistant that searches my products by meaning."
• "Ingest my products CSV into Vector Search and deploy a retail RAG agent."

Run the guided setup

Quick start asks for your GCP project ID and the product data location. Press Enter on the data question to use the bundled sample-products.csv. The skill then runs its setup script, which creates a BigQuery dataset and a Vector Search collection. The source notes this can take 2-5 minutes.

After setup succeeds, the skill sets the VECTOR_SEARCH_COLLECTION variable and lets you test with a query. You can test in the ADK web UI or with a direct Python smoke test.

• Quick start: project ID and data source only.
• Full setup: adds product fields level (Basic, Standard, Extended or Full) and GCP region.

Safety notes: scripts and network access

This skill runs scripts and uses the network. Its setup scripts create cloud resources, including BigQuery datasets and Vector Search collections, which can incur charges. Review the project, region and IAM settings before running setup, and do not use it with sensitive customer data until you have reviewed the IAM and network setup.

Use the workspace .venv Python and adk binaries, as the skill instructs, so the skill's own install is found.

• Setup creates cloud resources in your GCP project.
• Review IAM and network configuration before using sensitive data.
• Cleanup is handled by a separate cleanup script that the skill documents.

Tips for a smooth first run

Keep your CSV columns consistent with the product fields level you choose. The skill's validation rejects a Custom level. Semantic retrieval works on meaning; the bundled skill does not add structured filters on price or stock, so do not expect those from this version.

If something fails, the skill points to references/troubleshooting.md in its install folder.

• Match Full setup product fields to your CSV columns.
• Use the bundled demo CSV first to confirm the pipeline works.
• Stay in us-central1 unless you have confirmed another region works.