---
name: ecommerce.amazon-opportunity-report-by-keyword
description: Query Amazon business insight reports by keyword, covering six dimensions: market potential, product characteristics, user reviews, customer profiles, search trends, and pricing analysis with AI-powered comprehensive analysis. Trigger when users mention Amazon business insights, market opportunity reports, product selection reports, competitive landscape, consumer profiles, pricing analysis, niche market research, or similar terms. Even if the user does not explicitly say "business insights," trigger this skill whenever their request involves a comprehensive market opportunity assessment or report generation for an Amazon keyword.
---

# Amazon Market Opportunity Report

This skill guides you on how to generate comprehensive AI-powered market insight reports for Amazon keywords, helping sellers make data-driven product selection and market entry decisions.

## Core Concepts

This tool generates a comprehensive business insight report by analyzing six core dimensions of an Amazon keyword:

1. **Market Potential** - Search volume, demand trends, and growth opportunity
2. **Product Characteristics** - Common product attributes, materials, features
3. **User Reviews** - Customer sentiment, pain points, and satisfaction drivers
4. **Customer Profile** - Buyer demographics, preferences, and behavior patterns
5. **Search Trends** - Keyword popularity trajectory and seasonality
6. **Pricing Analysis** - Price distribution, competitive pricing landscape

The report is generated by AI from real-time Amazon data and delivered as a structured Markdown document. It is a snapshot analysis for decision support, not a real-time monitoring tool.

## Parameters

| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| site | string | Yes | Amazon marketplace code (currently US only) | US |
| keyword | string | Yes | The search keyword to analyze | - |

## Supported Marketplaces

Currently only **US** (United States) is supported. Always set `site` to `US`. If a user requests other marketplaces, inform them this tool currently only covers the US market.

## API Invocation

- **API Endpoint**: `POST /amazon/opportunity/reportByKeyword` (full parameters/responses/error codes see `references/api.md`)
- **Python Script**: `python scripts/amazon_opportunity_report.py '<JSON params>' [--inline]`
- **Cost Constraint**: This tool consumes credits; the same parameter combination is called only once per session by default, with a 24h local cache in the script. Do not automatically retry with different keywords, pagination, or zip codes after failures/empty results; inform the user about additional cost before continuing.

**Output Strategy (default script behavior)**:
- **Always** write the full response to `<cwd>/nexscope/<YYYY-MM-DD>/<session>/data/nexscope-amazon-opportunity-report-by-keyword-<timestamp>.json` (`<cwd>` is the working directory at script execution time, which in Claude Code is the current project directory; `<session>` is taken from the `SESSION_ID` environment variable, auto-grouped by user task; **do NOT write to /tmp** — error out if the current directory is not writable)
- Response body <= 8 KB: after writing to disk, print the full JSON to stdout
- Response body > 8 KB: after writing to disk, stdout outputs only a summary (top-level fields, common counts like `total`/`costToken`, length of the largest list field + first 3 samples)
- Add `--inline` to force full output to stdout (while still writing to disk)

**Data Reading Tips**: First check the summary to see if it is sufficient; 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.

## Authentication

Set the `NEXSCOPE_API_KEY` environment variable. If authentication fails (401/402) or you see insufficient balance errors, visit https://www.nexscope.ai/help/skills-external-access?co-from=skillNS to get an API Key or top up credits.

## Usage Examples

**1. Basic Market Opportunity Report**
```
Help me search for a business insight report on the US marketplace for the keyword "hair mousse travel size"
```

**2. Niche Product Research**
```
Generate a business insight report for the US marketplace keyword "magnetic shelves for whiteboard"
```

**3. Trend-Based Product Selection**
```
I want to understand the business insights for the US keyword "solar power ac unit" — generate a report
```

## Display Rules

1. **Present the report directly**: The API returns a Markdown-formatted report in the `stdout` field - display it as-is to the user
2. **No subjective advice**: Present the AI-generated analysis without adding your own business recommendations
3. **Clarify scope**: Remind users the report is based on a point-in-time snapshot and serves as a reference for decision-making
4. **Error handling**: When a query fails, explain the reason based on the `msg` field and suggest checking the keyword or trying again
5. **No secondary analysis**: This tool's output cannot be fed into data query tools for further processing - inform users if they attempt this

## Important Limitations

- **US only**: Currently only supports the United States marketplace (site = US)
- **Non-structured output**: Returns a Markdown report, not structured JSON data. Cannot be used with data query tools for secondary aggregation or analysis
- **Processing time**: Report generation involves AI analysis and may take longer than simple data lookups
- **Snapshot data**: Reports reflect data at the time of generation and are not continuously updated

## User Expression & Scenario Quick Reference

**Applicable** - Comprehensive keyword-level market analysis:

| User Says | Scenario |
|-----------|----------|
| "Help me analyze this keyword's market opportunity" | Market opportunity assessment |
| "Generate a market insight report for XX" | Full insight report |
| "What's the competitive landscape for XX" | Competition & pricing analysis |
| "Consumer profile for XX product" | Customer behavior insights |
| "Is XX keyword worth entering" | Market entry evaluation |
| "Product selection report", "Business insights" | Chinese market research requests |

**Not applicable** - Needs beyond comprehensive report generation:
- Real-time keyword ranking tracking (use ABA or SIF tools)
- Individual product detail lookup (use product detail tools)
- Historical price tracking (use Keepa)
- Review-level analysis for specific ASINs (use review tools)
- Advertising / PPC strategy

**Boundary judgment**: When users say "market analysis" or "product research", if they want a holistic, multi-dimensional overview of a keyword's market opportunity, this skill applies. If they need specific data points (exact sales numbers, individual product details, keyword rankings over time), direct them to the appropriate specialized tool.