Creates product search agents with semantic search and RAG on Google Cloud (Vertex AI Vector Search, 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, Vertex AI Vector Search collection setup, ADK agent scaffolding, evaluation, and Cloud Run deployment.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
La commande reste sur une seule ligne. Faites défiler horizontalement pour la vérifier avant de la copier.
Vous préférez une copie locale ? Téléchargez les fichiers actuellement disponibles dans SkillsMP.
Explorateur de fichiers
28 fichiers
Affichage de SKILL.md
SKILL.md
Instructions source · Aperçu en lecture seule
name
retail-product-search
description
Creates product search agents with semantic search and RAG on Google Cloud (Vertex AI Vector Search, 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, Vertex AI Vector Search collection setup, ADK agent scaffolding, evaluation, and Cloud Run deployment.
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
Q-MODE first. No preamble, no plan-proposing.
One question at a time. Show [default: ...]. Empty input = default.
Save answers to ./design-spec.md in the workspace as you collect them.
After interview, run scripts/setup.py (see Workspace Setup below).
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" && breakdone)
bash "$SKILL_DIR/scripts/bootstrap.sh"
bootstrap.sh finds a Python 3.10+ 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.
gemini-api (for Vertex AI API / 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)
Q
Question
Default
Q-A
GCP project ID?
$GOOGLE_CLOUD_PROJECT or gcloud config get-value project
Q-B
Where's your product data?
assets/sample-products.csv (bundled)
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.
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.
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:
data_source: assets/sample-products.csv → data_source: <Q-B answer> (only if user gave a non-default)
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."
Run .venv/bin/python "$SKILL_DIR/scripts/setup.py" --config ./design-spec.md
# 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
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.
Evaluate
cd <repo-root>
./vs eval retail-product-search --project-id $PROJECT
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
setup.py exits with 'NoneType' object has no attribute 'get'
design-spec.md was rewritten as plain Markdown instead of mutating the YAML-frontmatter template bootstrap copied. Wait for bootstrap to finish, then edit (not rewrite) ./design-spec.md — only change the field values inside the existing ---...--- frontmatter
adk web starts but /list-apps returns [] / browser shows "No agents found"
Bare adk resolved to a global Python that lacks the editable install. Kill it and restart with .venv/bin/adk web "$SKILL_DIR/scripts" --port 8765
MethodNotImplemented: 501 from Vector Search
VECTOR_SEARCH_COLLECTION has a newline. Re-export on one line
ModuleNotFoundError: google.adk
pip install -e "$SKILL_DIR" — google-adk is an unconditional dependency, no [adk] extra needed
Package requires Python: 3.9.X
venv used system Python 3.9. Recreate with python3.12 -m venv .venv
BILLING_DISABLED / PERMISSION_DENIED / API has not been used
GCP project setup — see 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:
