docs(amazon-shopping): document amazon product search skill

README.md

@@ -16,6 +16,7 @@ This repository contains practical OpenClaw skills and companion integrations. I
 
 | Skill | What it does | Path |
 |---|---|---|
+| `amazon-shopping` | Search Amazon.com product results with bounded web-automation, price/unit-price filters, delivery summaries, specs, ratings, and review metadata. | `skills/amazon-shopping` |
 | `flight-finder` | Collect structured flight-search inputs, run bounded multi-source travel searches, rank results in USD, and gate fixed-template PDF/email delivery through Luke’s sender path. | `skills/flight-finder` |
 | `gitea-api` | Interact with Gitea via REST API (repos, issues, PRs, releases, branches, user info). | `skills/gitea-api` |
 | `nordvpn-client` | Install, log in to, connect, disconnect, and verify NordVPN sessions across Linux CLI and macOS NordLynx/WireGuard backends. | `skills/nordvpn-client` |

docs/README.md

@@ -4,6 +4,7 @@ This folder contains detailed docs for each skill in this repository.
 
 ## Skills
 
+- [`amazon-shopping`](amazon-shopping.md) — Amazon.com product search with local web-automation, product filters, pricing, delivery, specs, and review metadata
 - [`flight-finder`](flight-finder.md) — Typed flight-search intake, bounded source orchestration, PDF report rendering, and Luke-sender email delivery
 - [`gitea-api`](gitea-api.md) — REST-based Gitea automation (no `tea` CLI required)
 - [`nordvpn-client`](nordvpn-client.md) — Cross-platform NordVPN install, login, connect, disconnect, and verification with Linux CLI and macOS NordLynx/WireGuard support

docs/amazon-shopping.md

@@ -0,0 +1,81 @@
+# Amazon Shopping Skill
+
+`amazon-shopping` searches Amazon.com product results with bounded, read-only web automation and deterministic local filtering.
+
+## Example Invocation
+
+```text
+use amazon-shopping to search for 100w led bulbs that cost less than $4 each and have over 200 reviews with a review score of more than 4.5 stars
+```
+
+## Helper Commands
+
+Run from the installed skill:
+
+```bash
+cd ~/.openclaw/workspace/skills/amazon-shopping
+scripts/search-products "USB-C charger under $30" --limit 10 --json
+scripts/search-products "100w led bulbs that cost less than $4 each and have over 200 reviews with a review score of more than 4.5 stars" --limit 5 --markdown
+scripts/search-products "USB-C cable with over 1000 reviews and rating over 4 stars" --limit 3 --json --skip-details
+```
+
+Use `--dry-run` to parse a request and show planned filters without navigating to Amazon:
+
+```bash
+scripts/search-products "USB-C charger under $30" --dry-run --json
+```
+
+## Dependency
+
+This skill depends on the workspace `web-automation` skill and its CloakBrowser runtime.
+
+```bash
+openclaw skills info web-automation
+cd ~/.openclaw/workspace/skills/web-automation/scripts
+node check-install.js
+```
+
+Setup or update the active `amazon-shopping` helper:
+
+```bash
+cd ~/.openclaw/workspace/skills/amazon-shopping
+npm ci
+npm run lint
+npm run typecheck
+npm test
+```
+
+## Fields
+
+Each result includes the product ASIN, title, source URL, price, unit price when visible, rating, review count, delivery summary, specs, feature bullets, seller, availability, sponsored marker, matched filters, missing fields, and extraction notes.
+
+Unknown or hidden fields stay unknown. The skill does not invent delivery dates, star histograms, prices, or review counts.
+
+## Filters
+
+Supported request filters include:
+
+- minimum rating
+- minimum review count
+- maximum product price
+- maximum unit price
+- result limit
+- maximum search pages
+
+`over 200 reviews` and `more than 4.5 stars` are strict comparisons. `at least 200 reviews` and `4.5 stars or better` are inclusive comparisons.
+
+## Guardrails
+
+This skill is for operator-directed product research, not purchasing automation.
+
+- It checks Amazon robots directives before live navigation.
+- It does not sign in, add to cart, purchase, access wishlists, submit reviews, crawl review pages, or bypass CAPTCHA/block pages.
+- It stops and reports a warning when Amazon returns a challenge, block, or disallowed robots path.
+- It uses default bounded operation: 15 results, 2 search pages, detail pages one at a time.
+
+## Live Smoke
+
+```bash
+cd ~/.openclaw/workspace/skills/amazon-shopping
+scripts/search-products "100w led bulbs that cost less than $4 each and have over 200 reviews with a review score of more than 4.5 stars" --limit 5 --json
+```