147 lines
5.1 KiB
Markdown
147 lines
5.1 KiB
Markdown
# 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
|
|
scripts/search-products 'sofa bed of 77 inches or wider, 4 stars or higher, 200+ reviews, shipped with Prime, delivery by tomorrow, top 10 by price' --limit 10 --json --markdown
|
|
```
|
|
|
|
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
|
|
```
|
|
|
|
Use single quotes when a request contains dollar amounts so the shell does not expand `$4`. `--max N` is accepted as a compatibility alias for `--limit N`.
|
|
|
|
## Install Or Update
|
|
|
|
Run these commands from the `stef-openclaw-skills` repo checkout:
|
|
|
|
```bash
|
|
cd ~/.openclaw/workspace/projects/stef-openclaw-skills
|
|
git pull --ff-only
|
|
rsync -a --delete \
|
|
--exclude node_modules \
|
|
--exclude dist \
|
|
--exclude coverage \
|
|
--exclude tmp \
|
|
--exclude out \
|
|
--exclude '*.log' \
|
|
--exclude '*.real.html' \
|
|
skills/amazon-shopping/ \
|
|
~/.openclaw/workspace/skills/amazon-shopping/
|
|
cd ~/.openclaw/workspace/skills/amazon-shopping
|
|
npm ci
|
|
```
|
|
|
|
Use the same sequence for a first install and for updates. `rsync --delete` keeps the active skill identical to the repo copy while preserving generated dependencies through the `node_modules` exclude. Always run `npm ci` after syncing because dependency changes are tracked through `package-lock.json`.
|
|
|
|
## Setup Verification
|
|
|
|
Verify the dependency skill, the active install, and OpenClaw discovery:
|
|
|
|
```bash
|
|
openclaw skills info web-automation
|
|
node "$HOME/.openclaw/workspace/skills/web-automation/scripts/check-install.js"
|
|
cd ~/.openclaw/workspace/skills/amazon-shopping
|
|
npm run lint
|
|
npm run typecheck
|
|
npm test
|
|
openclaw skills info amazon-shopping
|
|
```
|
|
|
|
For a quick parser-only check that does not browse Amazon:
|
|
|
|
```bash
|
|
scripts/search-products 'USB-C charger under $30' --dry-run --json
|
|
```
|
|
|
|
For a live smoke after install or update:
|
|
|
|
```bash
|
|
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 --markdown
|
|
```
|
|
|
|
## Dependency
|
|
|
|
This skill depends on the workspace `web-automation` skill and its CloakBrowser runtime.
|
|
|
|
## 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.
|
|
|
|
Markdown output uses chat-safe result blocks intended for direct user-facing answers in WhatsApp, Telegram, and terminals. Each product must keep a direct URL line:
|
|
|
|
```markdown
|
|
## Best Matches
|
|
|
|
1. Example Sofa Bed
|
|
Price: $399.99
|
|
Rating: 4.3 stars
|
|
Reviews: 250
|
|
Width: 83" OK
|
|
Prime: Prime OK
|
|
Delivery: FREE delivery Tomorrow OK
|
|
Link: https://www.amazon.com/dp/ASIN
|
|
```
|
|
|
|
The `OK` / `NO` marker is only attached to fields that correspond to requested filters. For example, `Prime OK` means the helper found a Prime signal on the search card or detail page; `not verified NO` means the product did not pass a requested Prime filter.
|
|
|
|
## Filters
|
|
|
|
Supported request filters include:
|
|
|
|
- minimum rating
|
|
- minimum review count
|
|
- maximum product price
|
|
- maximum unit price
|
|
- minimum width in inches
|
|
- Prime delivery
|
|
- delivery by today, tomorrow, or overnight
|
|
- sort by 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.
|
|
|
|
Examples of supported natural-language filters:
|
|
|
|
- `77 inches or wider`
|
|
- `shipped with Prime`
|
|
- `delivery by tomorrow`
|
|
- `overnight shipping`
|
|
- `top 10 by price`
|
|
- `rating 4.0 or better`
|
|
|
|
Equivalent CLI flags:
|
|
|
|
```bash
|
|
scripts/search-products 'sofa bed beige' --min-rating 4 --min-reviews 200 --min-width 77 --require-prime --delivery-by tomorrow --sort-by price --limit 10 --markdown
|
|
```
|
|
|
|
## 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.
|