retail-product-search

name: retail-product-search
description: >-
  Creates product search agents with semantic search and RAG on Google Cloud
  (Vector Search on Gemini Enterprise Agent Platform, BigQuery, embeddings). Use when the user wants to
  "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". Handles the full
  pipeline: catalog data ingestion to BigQuery, Gemini Enterprise Agent Platform Vector Search
  collection setup, ADK agent scaffolding, evaluation, and Cloud Run deployment.

metadata:
  author: Google
  license: Apache-2.0
  version: 0.2.0

Product Search Agent

Creates product search agents with semantic search and RAG on Google Cloud.

STOP — Q-MODE FIRST

If a catalog is already loaded (system context says "DEPLOYED search agent"

or provides a <catalog> block), skip Q-MODE and answer product queries

directly using the catalog.

Otherwise, your first message MUST be exactly this:

[skill: retail-product-search] active.
Q-MODE: Pick a setup mode? [default: 1]
  1. Quick start -- 2 questions, smart defaults, ~60s. Best for demos and first-timers.
  2. Full setup  -- 4 questions, ~2 min. Best for real builds.

Then stop and wait. Accept 1, quick, empty/Enter (Quick), or 2, full (Full).

Execution Rules

1. Q-MODE first. No preamble, no plan-proposing.
2. One question at a time. Show [default: ...]. Empty input = default.
3. Save answers to ./design-spec.md in the workspace as you collect them.
4. After interview, run scripts/setup.py (see Workspace Setup below).
5. User can say "configure more" mid-Quick-Start to switch to Full.

Workspace Setup

The skill has two locations:

• Install dir — where SKILL.md and scripts live (varies by host)
• Workspace — the agent's cwd; design-spec.md, .venv, and per-run state live here

By the end of this section the workspace must have .venv/ (with the skill

installed editable), design-spec.md, and SKILL_DIR exported in the shell.

Run this as ONE shell command — splitting it across tool calls loses state:

SKILL_DIR=$(for d in ~/.claude/skills ~/.agents/skills ~/.gemini/skills ~/.cursor/skills; do
  [ -f "$d/retail-product-search/SKILL.md" ] && echo "$d/retail-product-search" && break
done)
bash "$SKILL_DIR/scripts/bootstrap.sh"

bootstrap.sh finds a Python 3.11+ interpreter (with absolute-path fallback

for sandboxed shells), creates .venv, installs the skill editable, and

copies design-spec.md into the workspace.

All scripts run from the install dir against the workspace config. **Use

.venv/bin/python, not bare python** — bare python may resolve to a

Python without the skill's editable install on sys.path.

.venv/bin/python "$SKILL_DIR/scripts/setup.py" --config ./design-spec.md
.venv/bin/python "$SKILL_DIR/scripts/cleanup.py" --config ./design-spec.md --confirm

Details in [references/install-paths.md](references/install-paths.md).

Skill Dependencies

This skill works in conjunction with the following core Google Cloud skills:

• bigquery-basics (for database configuration guidelines)
• gemini-api (for Gemini Enterprise Agent Platform / Google Gen AI SDK best practices)

Verify if these skills are installed in your active skills directory. If they are missing, recommend the developer to install them by running:

npx skills add google/skills --skill bigquery-basics gemini-api

Mode 1: Quick Start (2 questions)

Accepted for Q-B: empty / default (bundled), /path/to/file.csv, or gs://....

Silent defaults: Extended fields, us-central1.

After Q-A and Q-B, do this automatically (don't ask the user to copy/paste).

Run these steps SEQUENTIALLY — do not parallelize. Steps 2-3 modify the

file bootstrap copies in step 1; running them concurrently is a race.

1. Run bootstrap first and wait for completion. bash "$SKILL_DIR/scripts/bootstrap.sh"

copies the YAML-frontmatter design-spec template into the workspace at

./design-spec.md. Do NOT touch ./design-spec.md until bootstrap exits.

1. Mutate the existing ./design-spec.md — do NOT rewrite it from scratch.

setup.py parses YAML frontmatter via _setup_utils.py. A Markdown-only

file fails with 'NoneType' object has no attribute 'get'. Use Edit / sed

to replace specific lines:

• gcp_project_id: "" → gcp_project_id: "<Q-A answer>"
• data_source: assets/sample-products.csv → data_source: <Q-B answer> (only if user gave a non-default)

1. Say: "Taking defaults for the rest. Running setup — this takes 2-5 min to

create a BigQuery dataset and Vector Search collection. Say 'configure

more' to switch to Full setup."

1. Run .venv/bin/python "$SKILL_DIR/scripts/setup.py" --config ./design-spec.md
2. Stream output. On non-zero exit, surface the error and check

[references/troubleshooting.md](references/troubleshooting.md)

1. On success, set VECTOR_SEARCH_COLLECTION and proceed to Test

Mode 2: Full Setup

Adds two more questions: product fields level and GCP region.

Otherwise identical to Quick Start.

When to Use

• E-commerce product search, shopping assistants, semantic catalog discovery

Don't use for generic document search, simple keyword search, or non-retail.

Project Tree

retail-product-search/
  assets/
    design-spec.md            # Source of truth -- filled by Q-MODE
    sample-products.csv       # Bundled 5-product demo catalog
  references/                  # Deep-dive docs (load on demand)
  scripts/
    agent.py                  # Reference ADK agent
    retrievers.py             # Vector Search retrieval logic
    setup.py                  # Pipeline driver (reads design-spec.md)
    bootstrap.sh              # Workspace bootstrap (called from Workspace Setup)
    validate_schema.py
    ingest_bigquery.py
    ingest_vertex_search.py
    cleanup.py

Customize: rewrite scripts/agent.py (see

[references/agent-example.md](references/agent-example.md)) and

scripts/retrievers.py with your product-specific fields.

Test

After setup.py succeeds, set the collection env var (one line, no newlines):

export VECTOR_SEARCH_COLLECTION="projects/$GOOGLE_CLOUD_PROJECT/locations/us-central1/collections/retail-skill-products-collection"

Then either:

With ADK (interactive UI):

# Use the WORKSPACE VENV's adk (not bare `adk`) so the skill's editable
# install is on sys.path. Bare `adk` may resolve to a global Python (pyenv,
# brew, etc.) whose ADK can't find the skill and reports an empty app list.
.venv/bin/adk web "$SKILL_DIR/scripts" --port 8765

Open http://127.0.0.1:8765, click scripts, query.

⚠️ Two things must be right:

• Point adk web at $SKILL_DIR/scripts, not at . — agent code lives

in the install dir, not the workspace. adk web . fails with "No agents

found in current folder".

• Use .venv/bin/adk, not bare adk — bare adk may launch the wrong

Python and silently fail to load the agent (UI loads, but /list-apps

returns [] and queries time out).

Without ADK (direct smoke test):

.venv/bin/python -c "from scripts.retrievers import search; print(search('laptop for video editing', top_k=3))"

Semantic-only retrieval — no structured filters on price, stock, or rating.

For demo queries and how to add structured filtering, see

[references/architecture.md](references/architecture.md).

Evaluate

cd "$SKILL_DIR"
uv run pytest

EVAL.yaml declares rubric (LLM-as-judge) + assertions (deterministic

checks). Target: 80%+ passing.

Deploy

Never deploy without explicit human approval.

Cloud Run service account needs roles/bigquery.dataViewer on the dataset and

roles/aiplatform.user on the project. Deploy via gcloud run deploy or your

org's existing tooling.

Gotchas

• No results: collection empty or VECTOR_SEARCH_COLLECTION not set
• Slow search: check region and top_k
• No structured filters: search() is pure semantic similarity. Price /

stock / currency filters happen client-side in the LLM, so results may

include items outside the constraint. Don't promise hard filters

• ADK session memory: if the retriever errored in earlier turns, the

model "learns" the tool is broken. Click "New Session" in adk web after

fixing the underlying issue

Troubleshooting

Most-common failures inline; full table in

[references/troubleshooting.md](references/troubleshooting.md).

MCP Migration

This skill uses gcloud CLI + Python SDKs (google-genai,

google-cloud-bigquery, google-cloud-aiplatform). Per

Phase 2 Skills guidelines, 1p skills

should prefer remote MCP tools when available. Migration map:

Completion Checklist

• [ ] Product fields level and data source confirmed
• [ ] Data ingestion ran; Vector Search populated
• [ ] retrieve_docs returns results in ADK web UI
• [ ] Evaluation passes success criteria
• [ ] Deployed (if beyond prototype)

References

Load on demand:

• [references/install-paths.md](references/install-paths.md) — host install dirs, Python fallback, bash -c rationale
• [references/dependencies.md](references/dependencies.md) — pip deps and install quirks
• [references/architecture.md](references/architecture.md) — what retrieval does (semantic-only), demo queries, structured-filter strategies
• [references/troubleshooting.md](references/troubleshooting.md) — full error table
• [references/agent-example.md](references/agent-example.md) — how agent.py + retrievers.py fit together
• [references/ingestion-scripts.md](references/ingestion-scripts.md) — per-script CLI reference