Ecommerce Amazon Alexa Search Skill for Claude

Amazon Alexa Shopping Assistant

This skill drives Amazon's storefront Alexa shopping assistant: pose a natural-language question and get an answer, a curated product list (with ASINs and links), and a set of follow-up questions Alexa is willing to continue with. Each call supports only one prompt. For multi-turn conversations, the agent must summarize prior context and concatenate it with the new question in a fresh call.

Core Concepts

• Single-turn per call: prompts is an array but only supports 1 element. Each API call sends exactly one question to Alexa and returns one answer. Do not pass multiple elements.
• Cross-call context is not preserved: every call starts a brand-new Alexa session. To ask follow-up questions, the agent must summarize the previous answer (key recommendations, ASINs, relevant context) and concatenate it with the new question as prompts[0] in a new call.
• Optional page context (url): pass an Amazon page URL only when you want the conversation anchored to a specific page (a category page, search results page, or product detail page). Do not pass a plain marketplace homepage URL like https://www.amazon.com/ -- it adds no useful context. Omit url entirely when there is no specific page to anchor on.
• Two output formats:
• markdown (default) -- a single readable Markdown report containing the question, Alexa's answer, recommended product groups, and follow-up questions.
• json -- a structured array under data, where each entry carries prompt, content, products (grouped recommendations), followUpQuestions, and screenshot.

resultsNum is the number of conversation turns Alexa actually answered; if 0, Alexa did not produce a usable reply for the input.

Parameters

| Parameter | Type | Required | Description | Default |

|-----------|------|----------|-------------|---------|

| prompts | string[] | Yes | Conversation prompts. Only 1 element is allowed per call. To ask follow-up questions, make a new call with context summary + new question as prompts[0]. | - |

| format | string | No | Response format: markdown returns a readable report; json returns a structured array. | markdown |

| url | string | No | Specific Amazon page URL (category, search results, or product detail) to anchor the conversation. Skip when there is no specific page; do not pass a plain homepage URL such as https://www.amazon.com/. | - |

Response Fields

| Field | Type | Description |

|-------|------|-------------|

| stdout | string | Markdown report when format=markdown: per-turn question, Alexa answer, recommended product groups, follow-up questions |

| data | array | Structured turns when format=json. Each item has prompt, content, products[], followUpQuestions[], screenshot |

| resultsNum | integer | Number of answered turns (0 = Alexa did not respond) |

| Outer code | integer | Only 0 succeeds; nonzero is a platform error |

| Outer msg | string / null | Upstream message, translated to English when needed; null if absent on success |

| costTime | integer | API latency in milliseconds |

| costToken | integer | Tokens consumed (only billed on success) |

| taskId | string | Upstream task identifier for tracing |

| type | string | Render hint: stdoutWorkbenches for markdown, json for json |

Structured data[*] shape (format=json)

| Field | Type | Description |

|-------|------|-------------|

| prompt | string | The question or follow-up sent for this turn |

| content | string | Alexa's natural-language answer |

| products[].title | string | Group title (e.g. "Top picks", "Best for running") |

| products[].items[].asin | string | Product ASIN |

| products[].items[].title | string | Product title |

| products[].items[].url | string | Product detail page URL |

| products[].items[].cover | string | Product cover image URL |

| products[].items[].price | string | Current price string (with currency) |

| products[].items[].originalPrice | string | List price / strikethrough price |

| products[].items[].score | string | Star rating |

| products[].items[].ratingsCount | string | Review count |

| products[].items[].describe | string | Short product blurb |

| followUpQuestions | string[] | Questions Alexa offers to continue with |

| screenshot | string | Screenshot URL for this turn |

How to Invoke

• API Endpoint: POST /amazon/alexaSearch (complete params/response/error codes in references/api.md)
• Python Script: python scripts/amazon_alexa_search.py '<JSON params>' [--inline]
• Cost constraint: This tool consumes credits; the same session and parameter combination is called only once by default, with a 24h local cache in the script. On failure or empty results, do not automatically retry with different keywords, pagination, or postal codes; inform the user about additional consumption before continuing to search.

Output strategy (script default behavior):

• Always write the full response to <cwd>/nexscope/<YYYY-MM-DD>/<session>/data/nexscope-amazon-alexa-search-<timestamp>.json (<cwd> is the working directory at script execution time, i.e. the current project directory in Claude Code; <session> is taken from the SESSION_ID env var, auto-grouped by user task; do not write to /tmp, error if current directory is not writable)
• Response body <= 8 KB: print full JSON to stdout after saving
• Response body > 8 KB: print only summary to stdout after saving (top-level fields, common counts like total/costToken, length of largest list field + first 3 samples)
• Add --inline to force full output to stdout (still saves to disk)

Data reading tip: Check the summary first to decide if it's enough; when specific fields are needed, prefer using jq or ConvertFrom-Json to extract from the saved json file on demand, avoiding loading the entire JSON into context.

How to Build Queries

• Front-load the user's intent in prompts[0] -- include marketplace cue ("on Amazon US"), use case, and any hard constraints (budget, key feature). Alexa weights the opening question heavily.
• One question per call -- prompts only accepts 1 element. Do not pass multiple elements.
• For follow-ups, summarize and re-ask -- when the user wants to continue the conversation, the agent must: (a) summarize the key points from the previous Alexa response (answer highlights, recommended ASINs, relevant context); (b) concatenate the summary with the new question; (c) send as prompts[0] in a new API call. Alexa has no memory of prior calls.
• Anchor with url only when there's a specific page -- pass a category, search results, or product detail URL when the user is reasoning over that page. Skip url for general questions; do not pass a plain homepage like https://www.amazon.com/.
• Pick format deliberately -- markdown is best for showing the user a polished answer; json is better when downstream code needs to extract ASINs, prices, or follow-up questions programmatically.

Usage Examples

1. Single-turn shopping question

{
  "prompts": ["best wireless earbuds for running on Amazon US under $100"]
}

2. Follow-up question (agent summarizes prior context and re-asks)

First call:

{
  "prompts": ["best electric kettle on Amazon US"]
}

Second call (agent summarizes the previous answer and appends the follow-up):

{
  "prompts": ["Previously Alexa recommended: 1) Cosori Electric Kettle (B07T1KY5TZ, $35.99, 4.7 star), 2) Mueller Ultra Kettle (B09KC7D3HR, $29.97, 4.5 star). Now compare these two on noise level and boil time."]
}

3. Question anchored to a category page

{
  "prompts": ["What are the most popular picks on this page?"],
  "url": "https://www.amazon.com/s?k=electric+kettle"
}

4. Structured output for downstream extraction

{
  "prompts": ["best gift ideas for a 10-year-old who likes science"],
  "format": "json"
}

Display Rules

• Render the Markdown directly when format=markdown: stdout is already structured with turn headings, product cards, and follow-up questions -- preserve that structure.
• Surface the recommended ASINs so the user can click through; show title, price, score/ratingsCount, and the product URL.
• Show the follow-up questions Alexa returned -- they are usable prompts the user can pick to continue digging. When the user picks one, summarize the current answer and use the selected follow-up as prompts[0] in a new call.
• Don't reroute to a data-analysis sandbox: the answer body is conversational and the recommended products are nested groups, not a flat tabular dataset suitable for SQL-like aggregation.
• Flag empty results: if resultsNum is 0 or data is empty, tell the user Alexa did not produce a usable reply and suggest rephrasing or anchoring with a url.
• Indicate freshness: results reflect Alexa's live answer at call time; mention this when the user asks about timing.
• Handle business errors: if the numeric outer platform code is nonzero, surface outer msg and suggest retrying with simpler prompts.

Important Limitations

• Alexa-driven, not deterministic: same prompts can yield different answers across calls -- Alexa's response varies with time, traffic, and context.
• No cross-call memory: each tool call is a fresh Alexa session; the agent must summarize prior context and embed it in the new question.
• One prompt per call: prompts only accepts 1 element. For follow-ups, the agent must summarize context + new question into a single prompts[0] and make a new call.
• Marketplace coverage: anchored on Amazon's storefront Alexa experience (primarily amazon.com); availability on non-US marketplaces depends on Alexa rollout.
• Output mix: primary value is the conversational answer plus a curated handful of products; this is not a substitute for SERP-wide product extraction.

User Expression & Scenario Quick Reference

Applicable -- natural-language conversational shopping on Amazon:

| User Says | Scenario |

|-----------|----------|

| "Use Alexa to recommend...", "Ask Amazon Alexa..." | Direct Alexa Q&A |

| "Chat to find product recommendations on Amazon...", "Conversational product selection" | Conversational discovery |

| "Also ask a follow-up / continue asking..." | Follow-up (agent summarizes prior result and re-asks in new call) |

| "Recommend from this page / this category...", "Ask again based on this page" | Page-anchored conversation (use url) |

| "best XX for YY under $Z on Amazon" | Goal + constraint + budget Q&A |

| "Compare the first two recommendations from Alexa" | Compare within Alexa's reply |

| "What else can Alexa ask / give me some follow-up ideas" | Surface follow-up questions |

Not applicable -- better routed elsewhere:

• Pulling the full SERP for a keyword with positions, sponsored flags, etc. (use the storefront search-simulation skill).
• Historical search-term analytics or volume trends (use the ABA data explorer).
• Detailed product detail / A+ / bullets for a known ASIN (use the Amazon product detail skill).
• Review-level sentiment analysis (use the Amazon reviews skill).
• Image-based similar product discovery (use the image search skill).
• Aggregated statistics over a flat product list (no structured table here).

Boundary judgment: when the user wants a conversation -- "ask Amazon, get a recommendation, then keep asking" -- this skill applies. If they want raw search-result rows, structured analytics, or a specific ASIN's data, route to the matching specialized skill instead.

Response handling

For the research HTTP response, require a numeric outer code equal to 0 before using data. Nonzero codes are platform failures; display outer msg without interpreting its wording as a retry instruction. Nexscope preserves upstream messages and translates Chinese to English; successful responses may have msg: null. HTTP 200 alone and nested business code / status do not replace the platform check. See references/api.md for response paths and task-specific states.

Authentication

Set the NEXSCOPE_API_KEY environment variable. If credentials are missing or expire, visit https://www.nexscope.ai/help/skills-external-access?co-from=skillNS to top up credits.