Linkfox Amazon Opportunity Search By Metrics

Amazon Opportunity Screener by Metrics

This skill guides you on how to reverse-search Amazon niches and keywords from a metrics pool aggregated from historical opportunity reports, helping sellers turn vague selection ideas (low competition, growing demand, blue ocean, pain-point opportunity, etc.) into concrete niche candidates.

Core Concepts

This tool exposes a queryable pool of niche-level metrics (~37 fields per record) distilled from past Amazon opportunity reports. Instead of generating a fresh report (forward analysis), it lets you reverse-filter the existing pool by 30+ business dimensions and returns matching (marketplace, keyword) records ranked by collection time (most recent first).

Records are at the niche / keyword level, not ASIN level. Each record represents a niche snapshot — its market size, growth, competition, price tiers, demographics, top features, and review themes.

Forward vs. reverse: Use linkfox-amazon-opportunity-report when the user has a keyword and wants a comprehensive AI report. Use this skill when the user has business criteria (filters) and wants to discover which keywords / niches fit.

Filter Dimensions

Filters are grouped into six business dimensions. All filter parameters are optional, but at least one of keyword / nicheName or any metric filter must be provided — fully empty calls are rejected.

See references/api.md for the full parameter list, types, value ranges, and response field map.

Supported Marketplaces

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

调用方式

• API 端点：POST /amazon/opportunity/searchByMetrics（完整参数/响应/错误码见 references/api.md）
• Python 脚本：python scripts/amazon_opportunity_screener.py '<JSON 参数>' [--inline]
• 成本约束：本工具会消耗算力；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。

输出策略（脚本默认行为）：

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-opportunity-search-by-metrics-<timestamp>.json（<cwd> 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；<session> 取自环境变量 SESSION_ID，按用户任务自动聚合；禁止写入 /tmp，当前目录不可写则报错）
• 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout
• 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 total/costToken、最大列表字段的长度 + 前 3 条样本）
• 加 --inline 强制全量打印到 stdout（同样落盘）

读数据建议：先看摘要判断是否足够；需要具体字段时优先用 jq或ConvertFrom-Json 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。

解决认证和算力问题

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

异常情况

• 未配置API Key：环境变量未配置 LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
• 响应401或402状态码
• 响应提示算力或余额不足：消息含"算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。

How to Build Queries

The user expresses business intent in natural language; you map it to the smallest viable set of filters. Principles:

1. Convert intent into specific bounds: "low competition" → nicheBrandCountLte: 20; "fast-growing" → nicheSearchVolumeYoyChangePctAtLeastGte: 100 (≥100% YoY); "newcomer-friendly" → featureNewAvgReviewCountAtLeastLte: 500.
2. Start narrow, then loosen: First call usually with 2–4 strong filters and limit=25. If the result set is empty or too small, drop or widen the most aggressive filter rather than adding new ones.
3. Pair complementary signals: Brand-level + product-level concentration (featureTop5BrandSharePctAtLeastLte + nicheTop5ProductClickSharePctAtLeastGte) reveals "brands fragmented but products concentrated" — a brand-extension entry signal.
4. Snake_case fragments for tag fields: featureEmergingTrendTagsContains, demoLifeStageTagsContains, reviewNegativeTop1Topic, etc. accept snake_case word fragments and use LIKE matching. Pass a root word (size, parent, cordless) to cover normalized variants.
5. Faithful to user intent: Don't silently add filters the user didn't ask for. If they only said "growing", just filter on growth — don't also constrain price unless they mentioned it.

Common Scenarios

1. Niche reverse-lookup by keyword

{"keyword": "whoop band", "limit": 25}

2. Newcomer-friendly low-competition niches

{"nicheBrandCountLte": 20, "featureNewAvgReviewCountAtLeastLte": 500, "limit": 25}

3. High-growth blue ocean (≥100% YoY, brands not yet flooding in)

{"nicheSearchVolumeYoyChangePctAtLeastGte": 100, "nicheBrandCountYoyChangePctAtLeastLte": 30, "limit": 25}

4. Mid-tier price gap (low-price dominates, mid-tier scarce)

{"priceEntryClickSharePctAtLeastGte": 70, "priceMidClickSharePctAtLeastLte": 5, "limit": 25}

5. Pain-point entry — strong size complaints

{"reviewNegativeTop1Topic": "size", "reviewNegativeTop1PctAtLeastGte": 70, "limit": 25}

6. Premium-friendly female-driven niches

{"demoGenderDominant": "female", "demoPrimaryIncomeTier": "high", "priceHighClickSharePctAtLeastGte": 25, "limit": 25}

7. Q4 seasonal niches with ≥100k peak search

{"nichePeakMonthGte": 11, "nichePeakMonthLte": 12, "nichePeakSearchVolumeAtLeastGte": 100000, "limit": 25}

8. Track niches around a known competitor brand

{"featureTopBrandsContains": "WHOOP", "limit": 50}

Display Rules

1. Present data only: Render the returned niches as a clean comparison table — niche name / keyword, market size, growth, brand count, price range, key tags. No subjective business advice.
2. Surface the active filters: Echo the filter set you used so the user can adjust ("当前筛选：品牌数 ≤ 20 且搜索量同比 ≥ 100%").
3. Time-snapshot reminder: Records reflect data at collection time and are not continuously updated. Mention this when results look stale or contradict a user's external knowledge.
4. Empty / few-result handling: If data is empty or very short, suggest widening the most aggressive filter rather than re-asking the user from scratch.
5. Error handling: When a query fails, explain the reason based on the msg field (most often the "fully empty parameters" guard) and suggest adding at least one filter.
6. No secondary aggregation: The results power frontend rendering and are not stored, so they cannot be fed into @智能数据查询 (intelligent data query) for further aggregation. If users ask for grouped statistics across niches, do the calculation locally or pull a wider limit first.