# Amazon Review Intelligence Extractor

> >

- **Type:** Skill
- **Install:** `agentstack add skill-serendipityoneinc-zoodata-skills-amazon-review-intelligence-extractor`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [SerendipityOneInc](https://agentstack.voostack.com/s/serendipityoneinc)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [SerendipityOneInc](https://github.com/SerendipityOneInc)
- **Source:** https://github.com/SerendipityOneInc/ZooData-Skills/tree/main/amazon-review-intelligence-extractor
- **Website:** https://apiclaw.io/

## Install

```sh
agentstack add skill-serendipityoneinc-zoodata-skills-amazon-review-intelligence-extractor
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Amazon Review Intelligence Extractor — 11 Dimensions, 1B+ Reviews

Pre-analyzed consumer insights. Pain points, buying factors, user profiles, differentiation gaps.

## Files
- **Script**: `{skill_base_dir}/scripts/zoodata.py` — run `--help` for params
- **Reference**: `{skill_base_dir}/references/reference.md` (field names & response structure)

## Credential
Required: `ZOODATA_API_KEY`. Get free key at [zoodata.ai/api-keys](https://zoodata.ai/en/api-keys)

## Input (one of)
- **Single ASIN**: "Analyze reviews for B09V3KXJPB"
- **Multi-ASIN**: "Compare review pain points across these 5 competitor ASINs"
- **Category-wide**: keyword/category name → resolve via `categories` first (need ≥3-level deep path)

## API Pitfalls (see zoodata skill for full list)
- `reviews/analysis` needs **50+ reviews**. Fallback chain when sample is insufficient:
  1. **Lightweight**: `realtime/product` ratingBreakdown — only star distribution, no themes
  2. **Full 11-dim insights**: see "Insufficient Data Fallback" section below — use the
     local toolkit (`reviews-raw` + `review-tag-prompt` + `review-reduce-prompt` +
     `review-aggregate`) to bypass `/reviews/analysis` entirely
- **labelType** is NOT an API request parameter — the API returns all 11 dimensions in one call. Filter by `labelType` client-side from the `consumerInsights` array.
- Category mode needs precise path (≥3 levels) — broad categories = diluted insights
- Field name is `reviewRate` (NOT the legacy `reviewPercentage` from API v1) for mention frequency
- ASIN-specific endpoints don't need `--category`; keyword-based ones do
- **Category auto-detection**: categoryPath is auto-detected from target ASIN. If `category_source` in output is `inferred_from_search`, confirm with user

## On Missing Key

When `ZOODATA_API_KEY` is not set (verify via `python {skill_base_dir}/scripts/zoodata.py check` — exits 2 if no key in env or `~/.zoodata/config.json`): follow the **"On Missing Key"** protocol in `zoodata/SKILL.md` — STOP before any call, link the user to https://zoodata.ai/en/api-keys, and DO NOT produce a "partial analysis from public knowledge" / "for reference only" fallback as a substitute.
## On 401 Invalid Key

When `zoodata.py` returns code 401: follow the **"On 401 Invalid Key"** protocol in `zoodata/SKILL.md` — STOP further calls, tell the user the key was rejected and direct them to api-keys, do not fabricate missing data.

## On 402 Credit Exhausted

When `zoodata.py` returns code 402: follow the **"On 402 Credit Exhausted"** protocol in `zoodata/SKILL.md` — STOP further calls, report partial findings already gathered, do not fabricate missing data.

## 11 Analysis Dimensions
`painPoints` · `issues` · `positives` · `improvements` · `buyingFactors` · `keywords` · `userProfiles` · `scenarios` · `usageTimes` · `usageLocations` · `behaviors`

## Unique Logic

### Analysis Modes
- **Category mode**: all reviews in category → market-level insights
- **ASIN mode**: specific products → competitive analysis
- Choose based on user intent. Category = broader, ASIN = deeper.

### Pain Point Impact Ranking
Rank differentiation opportunities by: **frequency × avg rating delta**
"Top pain point: durability — mentioned in 27/471 reviews (5.7%), avg rating 2.4 when mentioned"

| reviewRate | Frequency Level | Interpretation |
|------------|----------------|---------------|
| >10% | 🔴 Critical | Mentioned by 1 in 10 buyers — must address in product design 📊 |
| 5-10% | 🟡 Significant | Common complaint — differentiator if solved 📊 |
| 2-5% | 🟠 Notable | Worth mentioning in listing if you solve it 📊 |
| 3.5 | Mild — noticed but not deal-breaker 🔍 |

**Differentiation Priority** = High frequency + Low avgRating = Biggest opportunity 🔍. If top 3 pain points all have reviewRate >5% and avgRating 5%) should appear in title or first bullet 💡.

### Competitor Comparison
Align dimensions (pain points vs pain points) across products. If competitor review data unavailable, use brand-detail sampleProducts + note limitation.
- **Your pain point rate  competitor's**: Risk — address in product iteration 💡
- **Both high on same pain point**: Category-wide issue — solving it is a strong differentiator 🔍

## Composite Command
```bash
python3 {skill_base_dir}/scripts/zoodata.py review-deepdive --target-asin "" [--keyword ""] [--category ""]
```
Optional: `--comp-asins ","` for comparison.
Runs: reviews × 11 dimensions + competitors + realtime + market context + price/trend.
(`` are LITERAL — replace with actual values, no curly braces in commands.)

### Detecting when to fall back

After `review-deepdive` runs, programmatically inspect its JSON output for sparse
review aggregation. The composite continues past review failures, so success is NOT
proof of usable insights. Detection rule:

```python
import json
deepdive = json.load(open("deepdive.json"))
reviews_section = deepdive.get("reviews", {})
# review-deepdive currently makes one /reviews/analysis call per labelType (target_painPoints,
# target_positives, etc.). All-fail means switch to fallback.
all_failed = all(
    sub.get("success") is False
    or not (sub.get("data") or {}).get("consumerInsights")
    for sub in reviews_section.values()
    if isinstance(sub, dict)
)
target_review_count = (deepdive.get("target_realtime", {}) or {}).get("data", {}).get("ratingCount", 0)
# Fallback triggers if ANY of these are true:
needs_fallback = (
    all_failed
    or target_review_count _/` containing `raw.json`,
`tagged.json`, `clusters.json`, `insights.json`. Example:
```bash
WORK=/tmp/review_B0XXXXXXXX_$(date +%s) && mkdir -p $WORK
```

### Step 1 — Fetch raw reviews

```bash
python3 {skill_base_dir}/scripts/zoodata.py reviews-raw \
    --asin  [--marketplace US] [--max-pages 10] > $WORK/raw.json
# Cost: 1 credit/page, 10 reviews/page, hard cap 100 (10 pages).
# Stops automatically when nextCursor=null (small-volume ASINs may exhaust earlier).
# For cost control: --max-pages 5 = 50 reviews / 5 credits / ~30s.
```

Then save just the reviews array for downstream tooling:
```bash
python3 -c "import json,sys; d=json.load(open('$WORK/raw.json'))['data']['reviews']; json.dump(d,open('$WORK/reviews_array.json','w'),ensure_ascii=False)"
```

### Step 2 — Map (per-review tagging)

`review-tag-prompt` renders the prompt **but does NOT call any LLM** — YOU (this skill's
LLM) produce the JSON. The template is uniform per review, so render it ONCE to learn
the schema, then mass-produce tags for all reviews in a single in-context pass.

```bash
# Render the prompt for ONE review to learn the schema (do this once per skill run)
python3 {skill_base_dir}/scripts/zoodata.py review-tag-prompt \
    --review "$(python3 -c 'import json,sys; print(json.dumps(json.load(open(sys.argv[1]))[0]))' $WORK/reviews_array.json)" \
    [--product-title "..."] [--product-category "..."]
```

The schema you must produce per review (12 fields, all required, empty arrays for empties):
```json
{
  "sentiment": "positive|neutral|negative",
  "mentioned_scenarios": [], "mentioned_issues": [], "mentioned_positives": [],
  "mentioned_improvements": [], "mentioned_buying_factors": [],
  "mentioned_pain_points": [], "user_profiles": [],
  "mentioned_usage_times": [], "mentioned_usage_locations": [],
  "mentioned_behaviors": [], "keywords": []
}
```

After producing tags for all N reviews, save them as a JSON array preserving review order:
```bash
# Save your in-context output as the array (example structure)
cat > $WORK/tagged.json 150 unique candidates, split into
chunks of ~150, render the reduce prompt per chunk, and merge clusters across chunks
by case-insensitive canonical name match. Other dims rarely exceed 100 candidates.

### Step 4 — Aggregate (no LLM, pure local)

```bash
python3 {skill_base_dir}/scripts/zoodata.py review-aggregate \
    --reviews $WORK/raw.json \
    --tagged $WORK/tagged.json \
    --clusters $WORK/clusters.json > $WORK/insights.json
# Output structure matches /reviews/analysis:
#   { reviewCount, avgRating, sentimentDistribution, consumerInsights[], topKeywords[] }
# Each consumerInsight has: {element, labelType, count, reviewRate, avgRating}
```

Use the same Pain Point Impact Ranking and Differentiation Priority tables above —
**but apply the small-sample caveat** when `reviewCount 15 percentage points, **re-examine the Map tags before
publishing**. Common causes: LLM mis-classifying a 5★ "didn't love it but works" as
positive; non-English reviews mis-tagged. Document residual mismatch in Data Provenance.

### Language (required)

Output language MUST match the user's input language. If the user asks in Chinese, the entire report is in Chinese. If in English, output in English. Exception: API field names (e.g. `monthlySalesFloor`, `categoryPath`), endpoint names, technical terms (e.g. ASIN, BSR, CR10, FBA, credits) remain in English.

### Disclaimer (required, at the top of every report)

> Data is based on ZooData API sampling as of [date]. Monthly sales (`monthlySalesFloor`) are lower-bound estimates. This analysis is for reference only and should not be the sole basis for business decisions. Validate with additional sources before acting.

### Confidence Labels (required, tag EVERY conclusion)

- 📊 **Data-backed** — direct API data (e.g. "painPoint 'durability' mentioned by 27% of reviewers 📊")
- 🔍 **Inferred** — logical reasoning from data (e.g. "durability is the #1 differentiation opportunity 🔍")
- 💡 **Directional** — suggestions, predictions, strategy (e.g. "highlight durability in bullet point #1 💡")

Rules: Strategy recommendations and listing copy suggestions are NEVER 📊. User criteria override AI judgment.

**Aggregate-label rule (applies to ALL report output, not just fallback)**: NEVER attach 📊 to ANY element that aggregates or groups underlying content when ANY piece of that content is 🔍 or 💡. "Aggregate/grouping elements" include:
- Section headers at EVERY level (`#`, `##`, `###`, `####`) — including top-level summary sections like "Overall Score", "Verdict", "Executive Summary"
- Summary/score lines anywhere in the report (e.g. `## Overall Score — 27/100 · Grade F 📊` is WRONG if any Basis row inside is 🔍)
- Table **column** headers in comparison tables (e.g. `**Target ASIN** 📊` as a column label is WRONG if any cell in that column contains 🔍)
- Table row headers or row-aggregation labels (when the row aggregates multiple cells of mixed confidence)
- Any other visual grouping label — bullet-list group titles, callout box titles, etc.

A group-level 📊 implies the whole block/column/row is data-backed, which smuggles inferred/directional content into the 📊 tier via visual grouping. Either (a) **omit the group-level label entirely** (preferred when content mixes tiers), or (b) use the LOWEST confidence present inside (🔍 if any underlying content is 🔍; 💡 if any is 💡). This is a universal output-quality rule — it applies regardless of which fallback path (if any) was triggered.

**Emoji reservation rule (closely related)**: The three confidence symbols `📊 🔍 💡` are RESERVED for confidence labeling. NEVER use them as decorative prefixes on section headers, table headers, or any aggregate element — even when you also include a correct confidence suffix on the same line. Example:
- ❌ WRONG: `## 📊 Overall Score — 27/100 · Grade F 🔍` (the leading 📊 reads as a data-backed claim even though the trailing 🔍 is correct)
- ✅ RIGHT: `## Overall Score — 27/100 · Grade F 🔍` (no decorative emoji, just the proper confidence suffix)
- ✅ RIGHT: `## 🎯 Overall Score — 27/100 · Grade F 🔍` (use non-reserved decorative icons like 🎯 🧭 📋 📝 📂 🏁 🚨 🏆 🔔 when a visual prefix is desired)

Decorative emoji ≠ confidence label — but from a reader's perspective, a leading `📊/🔍/💡` is indistinguishable from a confidence claim. Reserve these three symbols EXCLUSIVELY for confidence annotation to avoid ambiguity.

### Data Provenance (required)

Include a table at the end of every report:

| Data | Endpoint | Key Params | Notes |
|------|----------|------------|-------|
| (e.g. Market Overview) | `markets/search` | categoryPath, topN=10 | 📊 Top N sampling, sales are lower-bound |
| ... | ... | ... | ... |

Extract endpoint and params from `_query` in JSON output. Add notes: sampling method, T+1 delay, realtime vs DB, minimum review threshold, etc.

### API Usage (required)

| Endpoint | Calls | Credits |
|----------|-------|---------|
| (each endpoint used) | N | N |
| **Total** | **N** | **N** |

Extract from `meta.creditsConsumed` per response. End with `Credits remaining: N`.

## API Budget: ~20-30 credits

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [SerendipityOneInc](https://github.com/SerendipityOneInc)
- **Source:** [SerendipityOneInc/ZooData-Skills](https://github.com/SerendipityOneInc/ZooData-Skills)
- **License:** MIT
- **Homepage:** https://apiclaw.io/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-serendipityoneinc-zoodata-skills-amazon-review-intelligence-extractor
- Seller: https://agentstack.voostack.com/s/serendipityoneinc
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.