/shop-scout

name: shop-scout
description: >-
  Comparison-shops any product across many online stores, finds the genuinely
  cheapest option after discounts, surfaces working coupons, and checks whether
  each seller is safe to buy from — for one product or a whole shopping list,
  any store, any region. Use this whenever the user wants to buy something
  online, asks where to buy a product or for the best/cheapest price, compares
  prices across stores (Noon, Amazon, Amazon.sa, Jarir, extra, Namshi,
  AliExpress, eBay, …), hunts for discount or promo codes (including first-order
  and social-media codes), asks whether a store/seller is legit or a scam, or
  hands over a shopping list to price out. It runs a 4-step pipeline per item —
  find sellers, rank by effective price (price − coupon + shipping), judge seller
  safety (Trusted / Mixed / Risky), and find working coupons — then prints a
  comparison table, a best-buy recommendation, and (for lists) a consolidated
  cart with a single-store bundle tip. Trigger even when the user does not say
  "shop-scout": e.g. "is aliexpress seller X legit", "cheapest place to buy a
  PS5 in Saudi", "find me a Noon coupon", "price-check these 5 things", or
  "compare prices for AirPods Pro". Not for building e-commerce or checkout
  features, stock or share prices, order tracking, or code review.

shop-scout

Stop hopping between store tabs. Give shop-scout a **product** or a **shopping list** and it will, for each item: find who sells it, rank sellers by the price you'll *actually* pay after discounts and shipping, judge whether each seller is safe, and dig up working coupons — then recommend the best buy and, across a list, the smartest single-store bundle.

This skill is **agent-agnostic**. It assumes only three generic capabilities, named however your runtime provides them:

• **web search** — issue a query, get back result URLs/titles/snippets.
• **fetch a URL** — retrieve a page's content as text/markdown.
• **run N tasks concurrently** — sub-agents where your runtime has them,

otherwise just sequential or concurrent calls.

Quality depends heavily on *how* you fetch pages. Major retailers (Amazon.sa, Noon, …) render prices with JavaScript and block naive fetchers. So shop-scout prefers a real scraping backend (Firecrawl) and falls back to plain fetch only when nothing better is configured. Read **Backend tiers** next — they are *not* equivalent.

---

Backend tiers (auto-detected — "use what you have")

Detect the backend in this exact order and announce which one you're using:

1. **`FIRECRAWL_API_URL` is set → self-hosted Firecrawl. ⭐ Recommended.** Your own Firecrawl (Docker) at that base URL. **No account, no API key, no quota** — and reliable extraction on JS-heavy stores. This is the setup that answers the usual objection to Firecrawl ("I don't want an account/quota"). One-time setup is in `references/self-host-firecrawl/` (a `docker-compose.yml` you bring up with `docker compose up -d`, then `export FIRECRAWL_API_URL=http://localhost:3002`). 2. **Else if `FIRECRAWL_API_KEY` is set → Firecrawl cloud.** Base URL `https://api.firecrawl.dev/v2`, header `Authorization: Bearer fc-…`. Same endpoints as self-host, plus server-side structured (`json`) extraction. Subject to your plan's quota. 3. **Else → built-in web search + fetch. Best-effort fallback only.** Zero setup, but it hits bot walls and JS-rendered prices on major retailers and can't reliably read live prices. On this backend you **do not print a comparison table** — you output the **honest research summary** (see **Output: decide the format first**) and point the user at Firecrawl.

`SHOP_BACKEND` overrides detection: `auto` (default) | `firecrawl` (force Firecrawl; requires URL or key) | `builtin` (force native fetch).

> Don't present the three tiers as equal in your output. If you ended up on > built-in, say so and point the user at self-host. If on Firecrawl, just use it.

How to actually call Firecrawl (endpoints, params, the search-first-then-scrape workflow, cloud vs self-host differences) lives in **`references/firecrawl-usage.md`** — read it before your first Firecrawl call. A ready-made wrapper, `$SKILL_DIR/scripts/firecrawl.sh`, auto-detects self-host vs cloud from the same env vars and works from any agent that can run a shell command.

> **`$SKILL_DIR`** — this skill's own directory (the folder containing this > `SKILL.md`, `references/`, and `scripts/`). Resolve it per install: on a Claude > Code plugin install it's `${CLAUDE_PLUGIN_ROOT}/skills/shop-scout`; for an > `npx skills` / manual / other-agent install it's wherever this `SKILL.md` > lives. Always reference bundled files through it, never a hardcoded path.

---

Configuration (env vars — all optional, sane defaults)

| Var | Default | Meaning | |---|---|---| | `SHOP_BACKEND` | `auto` | `auto` \| `firecrawl` \| `builtin` | | `FIRECRAWL_API_URL` | — | Self-host base URL, e.g. `http://localhost:3002`. Highest-priority backend. | | `FIRECRAWL_API_KEY` | — | Firecrawl cloud key (`fc-…`). **Never write it to a file or commit it.** | | `SHOP_SCOPE` | `both` | `saudi` \| `global` \| `both` — which store list to search. | | `SHOP_STORES` | — | Comma list of pinned/preferred stores; *extends* the bundled lists. | | `SHOP_PARALLEL` | `3` | Max products researched concurrently. Higher = faster **but more tokens and hits rate limits sooner**. | | `SHOP_MAX_LISTINGS` | `5` | Max listings scraped per product (token control). |

Read env vars from the environment at runtime. A documented template lives in `.env.example` — copy it to `.env`, fill values, and load it however your runtime does (`.env` is gitignored). The store lists are in `references/stores.md` and are meant to be edited.

---

The 4-step pipeline (run per product)

For each product, do these four steps in order. Stay disciplined about tokens (see **Token-efficiency rules**) — search broadly, scrape narrowly, extr