mostafa-drz/shop-research

Preferences

On startup, use Read to load ~/.claude/skills/shop-research/preferences.md. If missing, treat as first-run (see First-time detection below).

Defaults when no preferences exist:

• output-root: ~/Desktop/shop-research/ (confirmed on first run)
• default-sites: amazon, google-shopping
• max-candidates: 5
• currency: USD
• tone: friendly-cli (terse, direct, warm — not corporate)
• open-report: true (auto-open the HTML report when done)

Also load ~/.claude/skills/shop-research/feedback-journal.md if present — it contains thumbs-up/down on past recommendations. Summarize its signal (e.g., "prefers minimal aesthetic", "avoids fast-fashion brands") and carry that into ranking.

Context

On startup, use Bash to detect: today's date (date +%Y-%m-%d), and whether ~/Desktop/shop-research/ exists (ls or absence).

Command routing

Check $ARGUMENTS:

• help → show help, stop
• config → run config flow, stop
• reset → delete preferences + feedback journal, confirm, stop
• feedback → collect thumbs-up/down on the most recent research (see Feedback section), stop
• history → list recent research folders with titles and dates, stop
• setup or preflight → run the Chrome extension setup/onboarding flow (see Setup section), stop
• anything else → run the skill (starts with a preflight check — see Step 0)

Help

shop-research — Product research across Amazon, Google & specialty sites with a 2026 HTML report

Usage:
  /shop-research [what to find]                    Interactive research
  /shop-research [...] --for <recipient>           Who is this for? (e.g., "mom, loves gardening")
  /shop-research [...] --budget <range>            e.g., "under $50", "$100-200"
  /shop-research [...] --sites <list>              Override default sites (amazon,google,etsy,rei,...)
  /shop-research [...] --max-candidates <N>        How many finalists to include (default 5)
  /shop-research [...] --notes <text>              Extra criteria, preferences, exclusions
  /shop-research config                            Set preferences
  /shop-research reset                             Clear preferences + feedback journal
  /shop-research feedback                          Rate the last research (teaches the skill)
  /shop-research history                           List past research folders
  /shop-research setup                             Walk through Chrome extension setup
  /shop-research help                              This help

Examples:
  /shop-research "birthday gift for my dad — loves woodworking, under $75"
  /shop-research "standing desk" --budget "$300-600" --notes "manual crank ok, no glass tops"
  /shop-research "running shoes" --for "me, neutral arch, marathon training" --sites amazon,rei

Output:
  {output-root}/{YYYY-MM-DD}-{kebab-title}/
    ├── report.html              ← modern 2026 single-file report (open in browser)
    ├── data.json                ← structured data (products, reviews, scores)
    ├── candidates/
    │   ├── {slug-1}/
    │   │   ├── hero.png         ← product image
    │   │   ├── page.png         ← screenshot of listing
    │   │   └── notes.md
    │   └── ...
    └── sources.md               ← all URLs visited + reasoning trail

Current preferences:
  (loaded from preferences.md)

Config

Use AskUserQuestion to collect:

1. Output root — where should research folders live? (default: ~/Desktop/shop-research/)
2. Default sites — which e-commerce sites to search by default? (Amazon, Google Shopping, Etsy, eBay, specialty)
3. Max candidates — how many finalists per research? (3 / 5 / 8)
4. Currency & region — currency symbol and Amazon TLD (amazon.com / .co.uk / .de / ...)
5. Ethical filters — any brands or categories to always exclude? (free text)
6. Tone — friendly-CLI (terse, warm), detailed (more explanation), minimal (facts only)

Save to ~/.claude/skills/shop-research/preferences.md in the format:

# /shop-research preferences
Updated: {date}

## Defaults
- output-root: {path}
- default-sites: {comma-list}
- max-candidates: {N}
- currency: {USD|EUR|...}
- amazon-tld: {com|co.uk|...}
- tone: {friendly-cli|detailed|minimal}
- exclusions: {free text}

## Profile (optional — the user can edit)
- Favored brands:
- Avoided brands:
- Aesthetic: (minimal, maximalist, vintage, etc.)
- Sustainability: (important / nice-to-have / not a factor)
- Gift-giving style: (practical / sentimental / experiential)

## Learned
- (auto-appended as patterns emerge)

After saving, confirm with a warm one-liner: "Saved. I'll remember these for next time — and I'll keep learning as you give feedback."

Reset

Delete both ~/.claude/skills/shop-research/preferences.md and ~/.claude/skills/shop-research/feedback-journal.md. Confirm: "All cleared. I'll start fresh on the next research."

First-time detection

If no preferences file exists, show a warm onboarding (not a blocker):

First time running /shop-research — quick intro:

  I search Amazon, Google Shopping, and specialty sites in a real Chrome
  window you control. For each research I create a folder on your Desktop
  with screenshots, a data.json, and a single-file HTML report you can open
  anywhere.

  I get smarter over time. After each research you can run `/shop-research
  feedback` to tell me what worked — I save that and factor it into future picks.

  To browse the web, I need the Claude in Chrome extension. If you haven't
  set it up yet, run:  /shop-research setup
  Otherwise, continue and I'll auto-check the connection.

Then proceed to Step 0 (preflight). After the first successful research, ask inline if they want to save any quick prefs (budget style, aesthetic, sustainability priority) — don't force the full config flow.

Setup — Chrome extension onboarding

When invoked as /shop-research setup (or when Step 0 preflight fails and the user asks for help), walk through the Chrome extension setup. Reference: the official docs at https://code.claude.com/docs/en/chrome.

Prerequisites checklist (print this)

Before we go:

  1. Browser        Google Chrome or Microsoft Edge
                    (Brave, Arc, other Chromium browsers: not yet supported)
                    Windows WSL: not supported

  2. Plan           A direct Anthropic plan — Pro, Max, Team, or Enterprise
                    (Free tier and third-party providers like Bedrock/Vertex
                     don't have Chrome integration)

  3. Claude Code    Version 2.0.73 or higher
                    Check:  claude --version

  4. Extension      "Claude" by Anthropic, version 1.0.36 or higher
                    Install:
                    https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn
                    After install, pin it via the puzzle-piece icon.

Use Bash to run claude --version and surface the result so the user knows where they stand.

Enable Chrome in Claude Code

Tell the user exactly what to type (they run these themselves — you can't run slash commands for them):

Next:

  A.  Inside Claude Code, type:   /chrome
      Select "Enable" — or "Enabled by default" to auto-enable every session.

  B.  To verify, type:            /mcp
      Look for "claude-in-chrome" in the list.

  C.  Site permissions are managed inside the Chrome extension itself
      (click the extension icon → settings). At minimum, allow:
        amazon.com, google.com, shopping.google.com
      Plus any specialty sites you plan to search (etsy.com, rei.com, etc.)

Quick troubleshooting

If the user reports trouble, walk through in this order (from the official docs):

| Symptom | Fix | |---|---| | "Extension not detected" | Open chrome://extensions, confirm it's installed and enabled. Update if version < 1.0.36. | | "Browser extension is not connected" | Restart Chrome and Claude Code, then run /chrome → "Reconnect extension". | | Works once, then dies after a pause | Extension service worker went idle. Run /chrome → "Reconnect extension". | | "Receiving end does not exist" | Same as above — reconnect. | | "No tab available" | Ask Claude to create a new tab, then retry. | | First-time connection fails | Restart Chrome — the native messaging host config is picked up on Chrome startup. |

Native messaging host config (only relevant if deeper troubleshooting needed):

• macOS (Chrome): ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json
• macOS (Edge): ~/Library/Application Support/Microsoft Edge/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json
• Linux (Chrome): ~/.config/google-chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json

Confirm it works

Once the user says they're set up, run the preflight (Step 0 below). If it passes, say:

Connection good. You're ready — try:
  /shop-research "birthday gift for my dad — loves woodworking, under $75"

Workflow

Step 0 — Preflight (Chrome extension check)

Before anything else, verify the Claude-in-Chrome extension is connected. Without it, the research can't run.

1. Call mcp__claude-in-chrome__tabs_context_mcp.
2. If it succeeds → extension is live. Continue silently to Step 1.
3. If it fails (any error — "extension not detected", "receiving end does not exist", etc.) → do NOT retry blindly. Stop and show:

Hmm — the Claude-in-Chrome extension isn't responding.

Common causes:
  • Extension not installed  → https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn
  • Chrome integration not enabled in this session  → run  /chrome  and select "Enable"
  • Extension idle  → run  /chrome  → "Reconnect extension"
  • First time ever  → restart Chrome once after enabling, then retry

Need the full walkthrough?  Run:  /shop-research setup

Then stop. Don't attempt the research without a working extension — it will only produce an empty folder.

One retry allowed: after showing the message, if the user replies "retry" or "try again", call tabs_context_mcp once more. If it still fails, route them to /shop-research setup.

Step 1 — Understand the ask

Parse $ARGUMENTS for:

• What — free text before any --flag (e.g., "birthday gift for my dad — woodworking")
• --for <recipient> — who it's for (include context about them)
• --budget <range> — budget constraint
• --sites <list> — override default sites
• --max-candidates <N> — override default candidate count
• --notes <text> — additional criteria or exclusions

If what is missing or vague, ask ONE concise AskUserQuestion with 2-4 clarifying options (recipient, vibe, budget). Don't interrogate — pick the one clarification that most shapes the search.

If you have feedback-journal.md, mention in one line which past signal is shaping this: e.g., "Biasing toward [X] based on past thumbs-up."

Step 2 — Draft a search plan

Before opening the browser, draft a plan and show it:

Plan:
  ├── Query strategies: [2-3 search phrasings]
  ├── Sites: {default-sites or --sites override}
  ├── Shortlist target: {max-candidates} candidates
  └── Scoring criteria: [3-5 factors derived from the ask]

Reply 'go' to start, or tweak any of the above.

Wait for confirmation (or a tweak). This is the only hard gate — keep it fast.

Step 3 — Create the research folder

Generate a slug from the ask: {YYYY-MM-DD}-{kebab-summary-max-60chars}. Examples:

• 2026-04-18-dad-birthday-woodworking-under-75
• 2026-04-18-standing-desk-300-600

mkdir -p {output-root}/{slug}/candidates

Clear policy: only the per-research folder is created fresh. Never delete sibling folders or anything outside {output-root}/{slug}/.

Step 4 — Open Chrome and orient

1. Call tabs_context_mcp first to see what tabs exist — never reuse a prior session's tab IDs.
2. Create new tabs with tabs_create_mcp as needed (Amazon search URL + Google Shopping URL to start).
3. resize_window to a predictable viewport (e.g., 1440x900) for consistent screenshots.

Step 5 — Gather candidates

For each site in the plan:

1. Navigate to the search URL for that site (e.g., https://www.amazon.com/s?k=<url-encoded-query>).
2. Extract listings via javascript_tool: return an array of {title, url, price, rating, reviewCount, imageUrl} from the top results. Prefer structured extraction over raw get_page_text.
3. Score each listing against the criteria (use the factors from Step 2). Keep the top N.
4. Per-candidate deep dive — navigate to the product page, extract:
   • Full title, brand, price (current + MSRP if on sale)
   • Key specs / attributes
   • Rating + review count + review-score distribution if visible
   • 3-5 top positive review snippets (highest-rated helpful reviews)
   • 3-5 top negative / critical review snippets
   • Notable flags: return policy, shipping, warranty
5. Save hero image: use javascript_tool to extract the main image URL, then curl -L -o {candidates}/{slug}/hero.png "<url>".
6. Capture a page snapshot: use javascript_tool to capture the visible viewport as PNG (via html2canvas loaded dynamically, or serialize as data-URL and decode with Bash). Save as {candidates}/{slug}/page.png. If capture fails, log and continue — the hero image alone is sufficient.
7. Write {candidates}/{slug}/notes.md — one short file per candidate with all extracted fields.

Cross-source reviews (optional, adds depth): for each finalist, run one WebSearch for "<product name>" review to surface independent reviews (Wirecutter, Reddit, YouTube summaries). Quote 1-2 excerpts in the report.

Graceful degradation: if a site blocks extraction, log the issue in sources.md and skip — don't abort the whole research.

Step 6 — Score, rank, and pick a winner

Compute a composite score per candidate (0-100) from the scoring criteria. Produce:

• Top pick — best overall
• Runner-up — close second with a different trade-off
• Budget pick — cheapest that clears the quality bar (if price range spans widely)
• Splurge pick — highest-quality option if budget allows

Write data.json with the full structured data: candidates, scores, picks, sources, query metadata.

Step 7 — Generate the HTML report

Generate a single self-contained report.html (no external JS dependencies — inline everything). Aesthetic targets:

• Modern 2026 — clean typography (system font stack + Inter-style weights), generous whitespace, soft shadows, subtle gradients, rounded corners (12-16px), pill badges
• Light + dark mode via prefers-color-scheme — CSS variables only
• Mobile-responsive — single-column layout on small screens
• Intuitive — hero at top (top pick with verdict), then candidates grid, then detail pages per candidate accessible via in-page anchors
• Data-dense but scannable — pill chips for key specs, inline stars for ratings, mini bar charts for review distribution (pure CSS, no libs)
• No emoji soup — use color + typography to signal meaning, not emoji

Structure:

1. Header — brand mark + research title, date, budget, criteria summary (as pill chips). Inline the SVG from ~/.claude/skills/shop-research/icon.svg at ~32px next to the H1 with color: var(--accent) so it themes with light/dark mode. The icon is the grid-pick mark — a 3×3 dot grid with one cell haloed, signaling "N candidates → one pick" which matches this skill's behavior.
2. TL;DR — one-paragraph verdict + the top pick card with hero image, price, score ring, "why this won" (3 bullets)
3. Quick comparison table — all candidates, sortable by score/price/rating (client-side JS inline)
4. Candidate deep-dives — one section per candidate with:
   • Hero image
   • Price, rating, review count, score
   • Pros (3-5 bullets) and Cons (3-5 bullets)
   • Positive review quote + critical review quote
   • External review excerpt (if found)
   • "Good to know" metrics row (warranty, return window, shipping)
   • Link to the product page
5. Footer — sources, criteria recap, "rate this research" link to /shop-research feedback

Reference ~/.claude/skills/shop-research/reference/report-template.html if it exists (load on demand; otherwise generate from scratch following the aesthetic above).

Step 8 — Finalize and open

1. Write sources.md — every URL visited + one-line rationale per decision.
2. Print the final CLI report:

Done — {N} candidates researched in {duration}

  Top pick:     {title}  →  ${price}
  Runner-up:    {title}
  Budget pick:  {title}

Folder:   {output-root}/{slug}/
Report:   {output-root}/{slug}/report.html

Open it?  (y/N)  — or rate with:  /shop-research feedback

If open-report: true, run open {output-root}/{slug}/report.html.

Step 9 — Invite feedback

End with a soft prompt (not a blocker):

When you've had a look, run /shop-research feedback and tell me what worked. I'll keep getting sharper at your taste.

Feedback & learning

When invoked as /shop-research feedback:

1. Find the most recent research folder under {output-root}/.
2. Ask via AskUserQuestion:
   • Did the top pick feel right? (yes / yes with caveats / no, missed the mark)
   • What to weight more next time? (price / quality / brand / aesthetic / reviews / other)
   • Anything to avoid in future research? (free text)
3. Append to ~/.claude/skills/shop-research/feedback-journal.md:

## {research slug} — {date}
- Verdict: {yes/caveats/no}
- Weight more: {factors}
- Avoid: {free text}
- Signal extracted: {one-line generalization, e.g., "prefers quieter/minimal aesthetic over bold"}

4. If a clear pattern emerges across 3+ sessions (same brand avoided, same price sensitivity, same aesthetic), promote it from the journal to the ## Learned section of preferences.md. Mention the promotion: "Noticed you consistently avoid X — saving that as a standing preference."

The journal is human-editable. Respect whatever the user writes there directly.

Filename / folder naming rules

• Research folder: {YYYY-MM-DD}-{kebab-summary} — 60 chars max in the summary half
• Candidate folder: {kebab-product-short-name} — 40 chars max, derived from product title (not a counter)
• Never append -2, -3 — if two candidates would collide, differentiate by brand or model number

Principles

1. Real Chrome, explicit tabs — always tabs_context_mcp first; always create a new tab with tabs_create_mcp rather than reusing one from a prior session
2. Structured over scraped — prefer javascript_tool returning clean JSON over dumping get_page_text. Smaller context, higher accuracy
3. Per-research isolation — one folder per session; never delete or overwrite anything outside the current research folder
4. Non-interrogating onboarding — ask the minimum clarifying question that unblocks the search; save prefs silently as patterns emerge
5. Learning is explicit and editable — feedback lives in a human-readable journal; the user can read, edit, or wipe it anytime
6. Graceful degradation — a blocked site or a failed screenshot is logged and skipped; the research completes with what was possible
7. Stop on dialogs — never click elements that trigger browser alerts/confirms/prompts; the extension becomes unresponsive if a modal appears
8. Warm, terse CLI tone — direct sentences, no corporate filler, no emoji-heavy output; one friendly line at start and end is enough