diff --git a/docs/amazon-shopping.md b/docs/amazon-shopping.md
index 2c7fbd9..36d873f 100644
--- a/docs/amazon-shopping.md
+++ b/docs/amazon-shopping.md
@@ -14,25 +14,26 @@ 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 '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
+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`.
+
 ## 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
+node "$HOME/.openclaw/workspace/skills/web-automation/scripts/check-install.js"
 ```
 
 Setup or update the active `amazon-shopping` helper:
@@ -77,5 +78,5 @@ This skill is for operator-directed product research, not purchasing automation.
 
 ```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
+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
 ```
diff --git a/skills/amazon-shopping/SKILL.md b/skills/amazon-shopping/SKILL.md
index 36e6e79..8b7819b 100644
--- a/skills/amazon-shopping/SKILL.md
+++ b/skills/amazon-shopping/SKILL.md
@@ -13,8 +13,7 @@ Verify the browser dependency before live use:
 
 ```bash
 openclaw skills info web-automation
-cd ~/.openclaw/workspace/skills/web-automation/scripts
-node check-install.js
+node "$HOME/.openclaw/workspace/skills/web-automation/scripts/check-install.js"
 ```
 
 ## Search Products
@@ -22,10 +21,11 @@ node check-install.js
 Run the helper from the installed skill directory:
 
 ```bash
-cd ~/.openclaw/workspace/skills/amazon-shopping
-scripts/search-products "<user request>" --json
+"$HOME/.openclaw/workspace/skills/amazon-shopping/scripts/search-products" '<user request>' --json
 ```
 
+Use single quotes around product requests that contain dollar amounts so the shell does not expand `$4` or similar text. Use `--limit N`; `--max N` is accepted as a compatibility alias. If your execution tool supports a timeout option, set it to at least 600 seconds for live runs with detail enrichment. Use `--skip-details` only for a quick preview or when the user does not need specifications and delivery details.
+
 Default to at most 15 products unless the user asks for a different count. For requested counts above 30, ask before continuing or split the request into batches. Always include source URLs, report missing fields explicitly, and do not claim review histogram data unless it was visible and extracted.
 
 ## Guardrails
diff --git a/skills/amazon-shopping/src/cli.ts b/skills/amazon-shopping/src/cli.ts
index cf1331c..1cf39c0 100644
--- a/skills/amazon-shopping/src/cli.ts
+++ b/skills/amazon-shopping/src/cli.ts
@@ -25,7 +25,7 @@ Usage:
 Options:
   --json                     Print JSON output
   --markdown                 Print markdown output
-  --limit N                  Maximum products to return (default: 15)
+  --limit N, --max N         Maximum products to return (default: 15)
   --allow-large-limit        Permit limits above 30
   --min-rating N             Minimum rating score
   --min-reviews N            Minimum review count
@@ -70,13 +70,14 @@ export function parseCliRequest(argv: string[]): SearchProductsRequest {
     string: [
       "query",
       "limit",
+      "max",
       "min-rating",
       "min-reviews",
       "max-price",
       "max-unit-price",
       "max-search-pages"
     ],
-    alias: { h: "help" }
+    alias: { h: "help", max: "limit" }
   });
 
   const rawQuery = String(args.query ?? args._.join(" ")).trim();
diff --git a/skills/amazon-shopping/tests/cli.test.ts b/skills/amazon-shopping/tests/cli.test.ts
index 4e6610c..c5495bc 100644
--- a/skills/amazon-shopping/tests/cli.test.ts
+++ b/skills/amazon-shopping/tests/cli.test.ts
@@ -64,6 +64,12 @@ describe("amazon-shopping CLI", () => {
     assert.equal(parseCliRequest(["usb c cable", "--json", "--markdown"]).output, "both");
   });
 
+  it("accepts max as a natural agent alias for limit", () => {
+    const request = parseCliRequest(["100w led bulbs", "--max", "5"]);
+
+    assert.equal(request.limit, 5);
+  });
+
   it("normalizes natural-language filters for the target request", () => {
     const request = parseCliRequest([
       "100w led bulbs that cost less than $4 each and have over 200 reviews with a review score of more than 4.5 stars",