{"id":"e9e6f430-a534-40e6-b724-062bd1df9660","entityType":"agent","slug":"clawhub-apiclaw-amazon-competitor-intelligence-monitor","name":"amazon-competitor-intelligence-monitor","canonicalUrl":"https://www.xpersona.co/agent/clawhub-apiclaw-amazon-competitor-intelligence-monitor","canonicalPath":"/agent/clawhub-apiclaw-amazon-competitor-intelligence-monitor","generatedAt":"2026-10-10T11:54:22.186Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T09:28:49.759Z","emptyReason":null},"description":"Amazon competitor intelligence engine. Produces analytical output focused on a defined set of competitors: either a one-shot deep teardown (Full Scan: 28-35 credits, 11 endpoints, battle card, side-by-side comparison, pricing/review/inventory breakdown) OR sustained per-competitor monitoring with alerts (Quick Check: 5-10 credits, realtime polling, baseline diff). Input: keyword, ASIN(s), or brand — whatever identifies the competitor set to analyze. Output is per-competitor analytical insight tied to that specific set. Use when the user wants focused analysis on identified competitors: a one-shot teardown or an ongoing per-competitor watch. Use when user asks: analyze competitor B07XXX, battle card for ASIN Y, side-by-side competitor teardown, monitor a competitor brand, deep analysis of these 3 competitors, ongoing watch on a defined competitor set. Requires ZOODATA_API_KEY.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.5K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s17081rahwfg1emrhs1pmfhmq984gan3:amazon-competitor-intelligence-monitor","sourceUrl":"https://clawhub.ai/apiclaw/amazon-competitor-intelligence-monitor","homepage":"https://clawhub.ai/apiclaw/skills/amazon-competitor-intelligence-monitor","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/apiclaw/amazon-competitor-intelligence-monitor","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/apiclaw/skills/amazon-competitor-intelligence-monitor","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":40,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"amazon-competitor-intelligence-monitor technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T09:28:49.759Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T09:28:49.759Z","emptyReason":null},"stars":null,"forks":null,"downloads":1525,"packageName":null,"latestVersion":"1.1.9","tractionLabel":"1.5K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T09:28:49.758Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T09:28:49.759Z","lastCrawledAt":"2026-10-10T09:28:49.758Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T09:28:49.758Z","lastVerifiedAt":null,"highlights":[{"version":"1.1.9","createdAt":"2026-08-07T02:07:52.455Z","changelog":"Composite resolved_category_path metadata + ABA out-of-window date guidance; per-skill CLI command allowlists (COMMAND_NOT_ALLOWED enforcement); credential-source hardening; SKILL.md description trims. See CHANGELOG.","fileCount":8,"zipByteSize":56996},{"version":"1.1.8","createdAt":"2026-08-04T01:28:25.495Z","changelog":"Release v1.3.0: composite robustness (empty-target guard, category self-heal, terminal fail-fast, realtime retry + offline fallback), keyword workflow + shared CLI hardening, security declarations, release-notify CI","fileCount":7,"zipByteSize":54537},{"version":"1.1.7","createdAt":"2026-07-29T08:35:22.472Z","changelog":"Reference cleanup: stop 7 references mislabelling themselves as Market Entry Analyzer; per-skill endpoint scoping for narrow skills (#94)","fileCount":6,"zipByteSize":45658},{"version":"1.1.6","createdAt":"2026-07-28T14:00:59.206Z","changelog":"Security: remove leaked bundled key + credential/base-url hardening; clear LLM-review content flags; accurate credit reporting for composite + crawl-wait (#93)","fileCount":6,"zipByteSize":45643},{"version":"1.1.5","createdAt":"2026-07-28T07:11:11.331Z","changelog":"Capabilities & Data Flow declarations + CLI hardening (SkillSpector audit response, #91)","fileCount":8,"zipByteSize":46180},{"version":"1.1.4","createdAt":"2026-07-24T09:27:08.143Z","changelog":"ZooData rebrand + backend-contract release: correct 13 selection modes (fixes hard-422 on listingAge/badges preset values), mode documented as CLI-local (not an API param), category parser hardening (comma-safe, JSON array input), credential env renamed to ZOODATA_API_KEY (legacy APICLAW_API_KEY still works), realtime cold-start retry guidance, refreshed docs and API reference.","fileCount":8,"zipByteSize":45173},{"version":"1.1.1","createdAt":"2026-04-13T12:36:28.977Z","changelog":"amazon-competitor-intelligence-monitor 1.1.1 - Documentation updates in SKILL.md to clarify usage and operation details. - No functional changes to core logic; serves as a minor update focusing on improving instructions and references.","fileCount":18,"zipByteSize":44649},{"version":"1.1.0","createdAt":"2026-04-09T03:27:07.643Z","changelog":"Initial release","fileCount":17,"zipByteSize":43222}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17081rahwfg1emrhs1pmfhmq984gan3:amazon-competitor-intelligence-monitor","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17081rahwfg1emrhs1pmfhmq984gan3:amazon-competitor-intelligence-monitor` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/apiclaw/amazon-competitor-intelligence-monitor before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-apiclaw-amazon-competitor-intelligence-monitor/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-apiclaw-amazon-competitor-intelligence-monitor/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-apiclaw-amazon-competitor-intelligence-monitor/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-apiclaw-amazon-competitor-intelligence-monitor/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-apiclaw-amazon-competitor-intelligence-monitor/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-apiclaw-amazon-competitor-intelligence-monitor/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T11:54:22.182Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-apiclaw-amazon-competitor-intelligence-monitor/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-apiclaw-amazon-competitor-intelligence-monitor/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-apiclaw-amazon-competitor-intelligence-monitor/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-apiclaw-amazon-competitor-intelligence-monitor/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T09:28:49.759Z","emptyReason":null},"readme":"Skill: amazon-competitor-intelligence-monitor\n\nOwner: apiclaw\n\nSummary: Amazon competitor intelligence engine. Produces analytical output focused on a defined set of competitors: either a one-shot deep teardown (Full Scan: 28-35 credits, 11 endpoints, battle card, side-by-side comparison, pricing/review/inventory breakdown) OR sustained per-competitor monitoring with alerts (Quick Check: 5-10 credits, realtime polling, baseline diff). Input: keyword, ASIN(s), or brand — whatever identifies the competitor set to analyze. Output is per-competitor analytical insight tied to that specific set. Use when the user wants focused analysis on identified competitors: a one-shot teardown or an ongoing per-competitor watch. Use when user asks: analyze competitor B07XXX, battle card for ASIN Y, side-by-side competitor teardown, monitor a competitor brand, deep analysis of these 3 competitors, ongoing watch on a defined competitor set. Requires ZOODATA_API_KEY.\n\nTags: latest:1.1.9\n\nVersion history:\n\nv1.1.9 | 2026-08-07T02:07:52.455Z | user\n\nComposite resolved_category_path metadata + ABA out-of-window date guidance; per-skill CLI command allowlists (COMMAND_NOT_ALLOWED enforcement); credential-source hardening; SKILL.md description trims. See CHANGELOG.\n\nv1.1.8 | 2026-08-04T01:28:25.495Z | user\n\nRelease v1.3.0: composite robustness (empty-target guard, category self-heal, terminal fail-fast, realtime retry + offline fallback), keyword workflow + shared CLI hardening, security declarations, release-notify CI\n\nv1.1.7 | 2026-07-29T08:35:22.472Z | user\n\nReference cleanup: stop 7 references mislabelling themselves as Market Entry Analyzer; per-skill endpoint scoping for narrow skills (#94)\n\nv1.1.6 | 2026-07-28T14:00:59.206Z | user\n\nSecurity: remove leaked bundled key + credential/base-url hardening; clear LLM-review content flags; accurate credit reporting for composite + crawl-wait (#93)\n\nv1.1.5 | 2026-07-28T07:11:11.331Z | user\n\nCapabilities & Data Flow declarations + CLI hardening (SkillSpector audit response, #91)\n\nv1.1.4 | 2026-07-24T09:27:08.143Z | user\n\nZooData rebrand + backend-contract release: correct 13 selection modes (fixes hard-422 on listingAge/badges preset values), mode documented as CLI-local (not an API param), category parser hardening (comma-safe, JSON array input), credential env renamed to ZOODATA_API_KEY (legacy APICLAW_API_KEY still works), realtime cold-start retry guidance, refreshed docs and API reference.\n\nv1.1.1 | 2026-04-13T12:36:28.977Z | auto\n\namazon-competitor-intelligence-monitor 1.1.1\n\n- Documentation updates in SKILL.md to clarify usage and operation details.\n- No functional changes to core logic; serves as a minor update focusing on improving instructions and references.\n\nv1.1.0 | 2026-04-09T03:27:07.643Z | user\n\nInitial release\n\nArchive index:\n\nArchive v1.1.9: 8 files, 56996 bytes\n\nFiles: README.md (3883b), references/cli-contract.md (9156b), references/reference.md (9267b), scripts/allowed-commands.json (278b), scripts/zoodata.py (179106b), skill-card.md (2736b), SKILL.md (15796b), _meta.json (157b)\n\nFile v1.1.9:SKILL.md\n\n---\nname: amazon-competitor-intelligence-monitor\ndescription: >\n  Amazon competitor intelligence engine. Produces analytical output focused on\n  a defined set of competitors: either a one-shot deep teardown (Full Scan:\n  28-35 credits, 11 endpoints, battle card, side-by-side comparison,\n  pricing/review/inventory breakdown) OR sustained per-competitor monitoring\n  with alerts (Quick Check: 5-10 credits, realtime polling, baseline diff).\n  Input: keyword, ASIN(s), or brand — whatever identifies the competitor set\n  to analyze. Output is per-competitor analytical insight tied to that\n  specific set.\n  Use when the user wants focused analysis on identified competitors:\n  a one-shot teardown or an ongoing per-competitor watch.\n  Use when user asks: analyze competitor B07XXX, battle card for ASIN Y,\n  side-by-side competitor teardown, monitor a competitor brand, deep analysis\n  of these 3 competitors, ongoing watch on a defined competitor set.\n  Requires ZOODATA_API_KEY.\nmetadata:\n  version: \"1.1.9\"\n  author: SerendipityOneInc\n  homepage: https://github.com/SerendipityOneInc/ZooData-Skills\n  openclaw: {\"requires\": {\"env\": [\"ZOODATA_API_KEY\"]}, \"primaryEnv\": \"ZOODATA_API_KEY\"}\n---\n\n# ZooData — Competitor Intelligence Monitor\n\n> Know your enemy. Two modes: Full Scan + Quick Check. Respond in user's language.\n\n## Files\n\n| File | Purpose |\n|------|---------|\n| `{skill_base_dir}/scripts/zoodata.py` | **Execute** for all API calls (run `--help` for params) |\n| `{skill_base_dir}/references/reference.md` | Load for exact field names or response structure |\n| `{skill_base_dir}/monitor-data/` | Runtime storage (auto-created): config.json, baseline.json, history/, alerts.json |\n\n## Credential\n\nRequired: `ZOODATA_API_KEY`. Get free key at [zoodata.ai/api-keys](https://zoodata.ai/en/api-keys).\n\n## Capabilities & Data Flow\n\n- **Network**: only `https://api.zoodata.ai` (Bearer `ZOODATA_API_KEY`). Setting `ZOODATA_BASE_URL` to an untrusted host (anything other than `api.zoodata.ai` / `*.zoodata.ai` / localhost) makes the CLI **refuse the request and withhold the key** — the Bearer token is never sent to an untrusted host.\n- **Execution**: bundled shared ZooData CLI `{skill_base_dir}/scripts/zoodata.py` (Python 3, stdlib-only). This skill allows `categories`, `market`, `competitors`, `products`, `product`, `history`, `analyze`, `competitor-analysis`, `check`, plus the review fallback toolkit (`reviews-raw` / `review-tag-prompt` / `review-reduce-prompt` / `review-aggregate`). Do not invoke unrelated subcommands for this skill's tasks — the bundled manifest `{skill_base_dir}/scripts/allowed-commands.json` enforces this: the CLI refuses out-of-scope subcommands with a structured `COMMAND_NOT_ALLOWED` error before any API request.\n- **Local files**: a private temporary working dir (created with `mktemp -d`, removed when the fallback completes) during the review fallback; reads the optional credential store `~/.zoodata/config.json`.\n- **Sent to the API**: keywords, category paths, ASINs, marketplace/date and numeric filter values only. **Never sent**: budget, experience level, risk tolerance, or any other user-profile text — profile inputs map client-side to numeric filters.\n- **Credits**: every API call consumes account credits. For broad or ambiguous requests, state the estimated credit cost and confirm with the user before running multi-call scans. The composite `competitor-analysis` command executes ~17+ API calls (Full Scan, ~28-35 credits documented) in ONE invocation and has NO skip/trim flags — under a credit cap, use the granular commands instead.\n\n## Shared CLI Contract\n\nBefore selecting or invoking the first command, read and apply the local `references/cli-contract.md`. Reapply it after every granular or composite result and before any fallback, additional call, state write, interpretation, or user-facing report. Use this skill's fallback logic only when the shared contract classifies the result as non-terminal.\n\n### Local Interface Failure Output\n\nFor a terminal interface failure, respond in the user's language that the competitor scan could not be completed, then list succeeded and failed endpoint identifiers. Do not emit a battle card, threat score, alert, monitoring recommendation, or baseline update. Keep control tokens, parameters, and retry logs internal unless diagnostics are requested.\n\n## Input\n\nRequired: keyword or ASIN(s). Optional: my_asin, competitor_asins, brand.\nIf only ASIN given → derive keyword via `product --asin` then ask user to confirm.\nBrand queries MUST also include confirmed `--category`.\n\n## API Pitfalls (CRITICAL)\n\n1. **Category auto-detection**: categoryPath is auto-detected from keyword, ASIN, or top search result. If `category_source` in output is `inferred_from_search`, MUST confirm with user before trusting results\n2. **All keyword-based endpoints MUST include `--category`**; ASIN-specific endpoints do NOT need it\n3. **Brand + category**: a brand sells across categories — only analyze within locked subcategory\n4. **Use API fields directly**: revenue=`sampleAvgMonthlyRevenue` (NEVER price×sales), sales=`monthlySalesFloor`, concentration=`sampleTop10BrandSalesRate`\n5. **reviews/analysis**: needs 50+ reviews. Fallback chain when sample is insufficient:\n   1. **Lightweight**: `realtime/product` ratingBreakdown — only star distribution, no themes\n   2. **Full 11-dim insights** — bypass `/reviews/analysis` entirely:\n      a. `zoodata.py reviews-raw --asin X` → fetch up to 100 raw reviews (10 credits, ~60s)\n      b. For each review: render Map prompt via `zoodata.py review-tag-prompt --review '<json>'`\n         and have your own LLM produce JSON tags (sentiment + 11 dimensions)\n      c. Collect candidate phrases per dimension; for each dimension render\n         Reduce prompt via `zoodata.py review-reduce-prompt --label-type X --candidates '[...]'`\n         and have your LLM produce semantic clusters\n      d. `zoodata.py review-aggregate --reviews R --tagged T --clusters C`\n         → consumerInsights output compatible with `/reviews/analysis`\n   3. **Fallback caveats** (apply to the 4-step chain above — lessons from end-to-end validation):\n      - **Working dir**: `WORK=$(mktemp -d)` (private, 0700 — not a predictable path); remove it with `rm -rf \"$WORK\"` after `review-aggregate` succeeds or the fallback aborts\n      - **Step b CLI behavior**: `review-tag-prompt` RENDERS the prompt only; YOUR LLM produces the JSON. Render once to learn the schema, then produce tags for all N reviews in one in-context pass (don't call the CLI N times).\n      - **Step c candidate extraction** (Python one-liner):\n        `candidates = {d: sorted({el.strip().lower() for t in tagged for el in (t.get(d) or [])}) for d in DIMS}`\n      - **Small-sample rule (reviewCount<50)**: demote single-mention items 📊→🔍; NEVER attach table-level or section-header 📊 when any row inside is 🔍; suppress \"🔴 Critical\" verdicts on count=1\n      - **Scope**: fallback replaces ONLY the `/reviews/analysis` aggregation. This skill's primary workflow outputs (competitor metrics, brand ranking, pricing, etc.) remain valid — do not re-run them.\n\n## On Missing Key\n\nWhen `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`), stop before any evidence call. Tell the user that a ZooData API key is required, link to https://zoodata.ai/en/api-keys, and explain that the key may be set in the environment or local config. Do not substitute public knowledge or a \"for reference only\" analysis.\n## On 401 Invalid Key\n\nWhen `_transport.status=401`, stop further calls, tell the user that the configured key was rejected, direct them to https://zoodata.ai/en/api-keys, and do not fabricate missing data.\n\n## On 402 Credit Exhausted\n\nWhen `_transport.status=402`, stop further calls. Report where the workflow stopped, any compatible partial findings already gathered, and returned credit metadata when present; direct the user to https://zoodata.ai/en/pricing and do not fabricate missing data.\n\n## Mode Selection\n\n- **Full Scan** (~28-35 credits): First run, no baseline.json, explicit request, or weekly refresh\n- **Quick Check** (~5-10 credits): Cron trigger, baseline exists, \"check competitors\"\n\n## Full Scan Flow\n\n1. `competitor-analysis --keyword X [--category Y] [--my-asin Z]` (composite, auto-detects category)\n2. If `category_source` is `inferred_from_search`, confirm with user before presenting results\n3. Analyze & score → save baseline to `{skill_base_dir}/monitor-data/` → offer Auto-Monitor\n\n## Quick Check Flow\n\n1. Load config.json + baseline.json from `{skill_base_dir}/monitor-data/` (missing → fall back to Full Scan)\n2. Poll `product --asin {asin}` for each tracked ASIN\n3. Diff against baseline with tiered alerts → update baseline → offer Auto-Monitor\n\n## Alert Tiers\n\n| 🔴 Critical | 🟡 Watch | 🟢 Opportunity |\n|-------------|----------|----------------|\n| Price change > threshold | FBA↔FBM switch | Competitor stock-out |\n| BSR crash > threshold | Rating change | Bullet/image changes |\n| Buy Box owner changed | Abnormal review growth | Variant added/removed |\n| | Title modified | |\n\n## Competitive Score (per competitor, 1-100)\n\n| Dimension | Weight | 80-100 (Strong) | 50-79 (Moderate) | 0-49 (Weak) |\n|-----------|--------|-----------------|-------------------|-------------|\n| Sales Dominance | 25% | Top 3 in category, >5K units/mo 📊 | Top 20, 1K-5K units/mo 📊 | Below Top 20, <1K units/mo 📊 |\n| Brand Strength | 20% | Brand in CR10, 5+ SKUs, wide price range 📊 | Known brand, 2-4 SKUs 📊 | Unknown brand, single SKU 📊 |\n| Listing Quality | 20% | 7+ images, 5 bullets, A+, optimized title 📊 | 5-6 images, basic bullets 📊 | <5 images, weak bullets, no A+ 📊 |\n| Customer Satisfaction | 20% | Rating ≥4.5, <3% 1-star, positive sentiment 📊 | 4.0-4.4, 3-8% 1-star 📊 | <4.0 or >8% 1-star 📊 |\n| Trend Momentum | 15% | BSR improving 30d, sales growth >10% 🔍 | BSR stable, flat sales 🔍 | BSR declining, sales drop 🔍 |\n\n### Competitive Threat Level\n| Total Score | Threat | Interpretation |\n|-------------|--------|---------------|\n| 80-100 | 🔴 Dominant | Hard to compete head-on; find differentiation or avoid price band 💡 |\n| 50-79 | 🟡 Competitive | Beatable with better listing, pricing, or reviews 💡 |\n| 0-49 | 🟢 Vulnerable | Weak competitor; opportunity to capture share 💡 |\n\n### Market Structure Analysis\n- **CR10 > 70%**: Concentrated market — new entrants need strong differentiation or niche positioning 🔍\n- **CR10 40-70%**: Moderately competitive — room for well-positioned products 🔍\n- **CR10 < 40%**: Fragmented — opportunity for brand building 🔍\n- **Top brand share > 25%**: Category leader dominance — avoid direct competition in their price band 💡\n- **New SKU rate > 15%**: Active market with frequent new entrants 📊\n- **New SKU rate < 5%**: Mature/stagnant market, high barriers 🔍\n\n## Auto-Monitor Prompt\n\nAfter EVERY run, offer: \"Set up automatic monitoring? I can generate a scheduled Quick Check.\" Provide platform-specific setup (OpenClaw `/cron`, ChatGPT Scheduled Tasks, Claude Projects).\n\n## Output Spec\n\nFull Scan sections: Battlefield Overview → Competitor Matrix → Brand Power Ranking → Price Map → 30-Day Trends → Review Battle → Listing Audit → Competitive Scores → Battle Strategy → Data Provenance → API Usage.\n\n### Language (required)\n\nOutput 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.\n\n### Disclaimer (required, at the top of every report)\n\n> 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.\n\n### Confidence Labels (required, tag EVERY conclusion)\n\n- 📊 **Data-backed** — direct API data (e.g. \"CR10 = 54.8% 📊\")\n- 🔍 **Inferred** — logical reasoning from data (e.g. \"brand concentration is moderate 🔍\")\n- 💡 **Directional** — suggestions, predictions, strategy (e.g. \"consider entering $10-15 band 💡\")\n\nRules: Strategy recommendations are NEVER 📊. Anomalies (>200% growth) are always 💡. User criteria override AI judgment.\n\n**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:\n- Section headers at EVERY level (`#`, `##`, `###`, `####`) — including top-level summary sections like \"Overall Score\", \"Verdict\", \"Executive Summary\"\n- Summary/score lines anywhere in the report (e.g. `## Overall Score — 27/100 · Grade F 📊` is WRONG if any Basis row inside is 🔍)\n- Table **column** headers in comparison tables (e.g. `**Target ASIN** 📊` as a column label is WRONG if any cell in that column contains 🔍)\n- Table row headers or row-aggregation labels (when the row aggregates multiple cells of mixed confidence)\n- Any other visual grouping label — bullet-list group titles, callout box titles, etc.\n\nA 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.\n\n**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:\n- ❌ WRONG: `## 📊 Overall Score — 27/100 · Grade F 🔍` (the leading 📊 reads as a data-backed claim even though the trailing 🔍 is correct)\n- ✅ RIGHT: `## Overall Score — 27/100 · Grade F 🔍` (no decorative emoji, just the proper confidence suffix)\n- ✅ RIGHT: `## 🎯 Overall Score — 27/100 · Grade F 🔍` (use non-reserved decorative icons like 🎯 🧭 📋 📝 📂 🏁 🚨 🏆 🔔 when a visual prefix is desired)\n\nDecorative 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.\n\n### Data Provenance (required)\n\nInclude a table at the end of every report:\n\n| Data | Endpoint | Key Params | Notes |\n|------|----------|------------|-------|\n| (e.g. Market Overview) | `markets/search` | categoryPath, topN=10 | 📊 Top N sampling, sales are lower-bound |\n| ... | ... | ... | ... |\n\nExtract endpoint and params from `_query` in JSON output. Add notes: sampling method, T+1 delay, realtime vs DB, minimum review threshold, etc.\n\n### API Usage (required)\n\n| Endpoint | Calls | Credits |\n|----------|-------|---------|\n| (each endpoint used) | N | N |\n| **Total** | **N** | **N** |\n\nExtract from `meta.creditsConsumed` per response. End with `Credits remaining: N`.\n\n## API Budget\n\nFull Scan: ~28-35 credits (all 11 endpoints via composite). Quick Check: ~5-10 credits (realtime/product × N ASINs).\n\nFile v1.1.9:README.md\n\n# Amazon Competitor Intelligence Monitor — ZooData Agent Skill\n\n> Know your enemy. Full Scan + Quick Check. Always watching.\n\n## What This Skill Does\n\nDeep competitor intelligence with two operational modes. **Full Scan** delivers a complete competitive landscape — competitor matrix, brand ranking, pricing map, review battle, and battle strategy. **Quick Check** polls tracked ASINs against a saved baseline and fires tiered alerts when something changes.\n\n### What Makes This Different\n\n- **Dual-mode**: Full Scan (~28-35 credits) for deep analysis, Quick Check (~5-10 credits) for lightweight monitoring\n- **Three-tier alerts**: 🔴 Critical (price crash, Buy Box lost), 🟡 Watch (FBA switch, rating shift), 🟢 Opportunity (stock-out, listing changes)\n- **Competitive Score**: Each competitor scored 1-100 across 5 dimensions (sales, brand, listing, satisfaction, trend)\n- **Auto-Monitor**: Offers scheduled Quick Check setup after every run\n\n## Install\n\n```bash\nnpx skills add SerendipityOneInc/ZooData-Skills\n```\n\nSelect **Amazon Competitor Intelligence Monitor** when prompted.\n\n## API Key Setup\n\n1. Get a free key at [zoodata.ai/api-keys](https://zoodata.ai/en/api-keys) — 1,000 free credits, no credit card\n2. Set the environment variable:\n   ```bash\n   export ZOODATA_API_KEY='hms_live_xxxxxx'\n   ```\n\n## Data & Privacy\n\n- Each run sends your tracked ASINs, competitor ASINs, keywords, category paths, and marketplace/date/numeric filters to the ZooData API (`api.zoodata.ai`). With scheduled Quick Check monitoring enabled, this happens on a recurring, unattended basis.\n- Nothing else is transmitted: no budget, seller-account, or free-text profile data leaves your machine.\n- Local state: baselines, history, and alert files under the skill's `monitor-data/` folder persist between runs for change detection. Delete the folder anytime to reset monitoring and remove the retained data.\n- Scheduled monitoring is opt-in — the skill asks for explicit confirmation before enabling recurring runs. Every API call consumes account credits.\n\n## Example Prompts\n\n- *\"Analyze my competitors for ASIN B0XXXXXXXX in the yoga mat market\"*\n- *\"Run a full competitor scan for keyword 'silicone spatula'\"*\n- *\"Quick check my tracked competitors\"*\n- *\"Who are the top competitors for 'dog harness' and how do I beat them?\"*\n- *\"Monitor competitor price changes and alert me on anomalies\"*\n\n## What You Get\n\n| Section | Description |\n|---------|-------------|\n| ⚔️ Battlefield Overview | Market size, player count, concentration |\n| 📊 Competitor Matrix | Side-by-side comparison of all key competitors |\n| 🏅 Brand Power Ranking | Brand strength scores and market share |\n| 💰 Price Map | Price positioning across competitors |\n| 📈 30-Day Trends | BSR, price, and sales movement |\n| 💬 Review Battle | Rating, sentiment, pain points per competitor |\n| 📋 Listing Audit | Image, bullet, A+ content comparison |\n| 🎯 Battle Strategy | Actionable recommendations to outperform |\n| 🚨 Alerts (Quick Check) | Tiered change detection vs baseline |\n\n## API Endpoints Used\n\n| Endpoint | Purpose |\n|----------|---------|\n| `categories` | Category resolution |\n| `markets/search` | Market context |\n| `products/search` | Product landscape |\n| `products/competitors` | Competitor discovery |\n| `realtime/product` | Live competitor data |\n| `reviews/analysis` | Sentiment & pain points |\n| `products/price-band-overview` | Price band context |\n| `products/price-band-detail` | Detailed price analysis |\n| `products/brand-overview` | Brand concentration |\n| `products/brand-detail` | Per-brand breakdown |\n| `products/history` | Trend analysis |\n\n## Credit Cost\n\nFull Scan: ~28-35 credits. Quick Check: ~5-10 credits.\n\n## Powered By\n\n[ZooData](https://zoodata.ai) — The data infrastructure built for agents. 200M+ Amazon products, 1B+ reviews, real-time signals.\n\nFile v1.1.9:_meta.json\n\n{\n  \"ownerId\": \"kn78k155f6rbh2j8r8yjx8r2e18304q9\",\n  \"slug\": \"amazon-competitor-intelligence-monitor\",\n  \"version\": \"1.1.9\",\n  \"publishedAt\": 1786068472455\n}\n\nFile v1.1.9:references/cli-contract.md\n\n<!-- Canonical source - do not edit copies under amazon-* skill directories directly -->\n\n# ZooData CLI Contract\n\n## Ownership and application\n\nThis file owns the project-wide caller contract before and after every bundled `{skill_base_dir}/scripts/zoodata.py` invocation. Read it before selecting the first command, then apply it after each granular or composite result and before any additional API/tool call, fallback, state write, interpretation, or user-facing report.\n\nIt owns the shared invocation form, command-identity validation, execution-environment permission handling, caller/CLI responsibilities, composite-result reuse, result acquisition, transport-status precedence, terminal-interface classification, retry ownership, and partial-result handling. It does not own skill-specific command allowlists, endpoint request/response fields, business interpretation, scenario selection, conclusion authority, or any user-facing failure/report rendering.\n\n## Invocation interface\n\n1. Invoke the bundled client as `python {skill_base_dir}/scripts/zoodata.py [global options] <subcommand> [subcommand options]` using the active skill's local copy.\n2. Place global options before the subcommand. Treat top-level and subcommand `--help` as the live invocation contract; help inspection makes no API request and consumes no credits.\n3. Use the active skill to select the allowed workflow and command scope. Use this contract to validate and execute that selection; do not let this shared file select a business workflow.\n4. Distinguish API/evidence commands from local-only diagnostic, prompt-rendering, and aggregation commands according to the selected subcommand's help. Do not attribute an API call or credit use to a local-only command.\n5. Credential resolution is owned by the bundled CLI. Invoke it directly; do not inspect local credential stores or pre-resolve, compare, export, or override credential values in the caller.\n\n## Command identity and composite reuse\n\n1. Inspect the bundled CLI's top-level `--help` and the selected subcommand's `--help` before invocation. Execute only an exact literal subcommand exposed by the current client and allowed by the active skill.\n2. Treat API endpoint identifiers and composite result keys as data identities, not CLI command names. Never derive a subcommand from either identity or invent an alias.\n3. Treat a successful composite command's structured output as the evidence bundle for that run. Perform selection, narrowing, transformation, extraction, and formatting locally.\n4. Do not make an additional API call solely to reread, reshape, or narrow evidence already present in the composite bundle.\n5. A granular call after a composite is allowed only for evidence absent from the bundle when the active skill's workflow or an explicit non-terminal fallback requires it.\n6. A keyword-driven composite resolves the working category through a fallback chain and records the outcome in `meta`: `meta.category_source` states how it resolved and `meta.resolved_category_path` carries the path used. An empty top-level `categories` section together with a non-null `meta.resolved_category_path` is successful fallback resolution (a multi-word product phrase not matching a category name), not missing data; read the resolved path and `category_source` before treating category evidence as absent.\n\n## Execution-environment permission gate\n\nApply this gate before classifying a connection or network failure as a CLI/API interface failure.\n\n1. Inspect the execution tool's permission profile and diagnostics. When they indicate, or strongly suggest, that a host sandbox or network policy blocked the request, treat the result as unresolved execution permission rather than endpoint failure.\n2. Use the execution tool's permission or escalation mechanism to request access and rerun the exact unchanged CLI command. Do not first emit the skill's interface-failure notice or a succeeded/failed endpoint ledger.\n3. A permission-approved rerun is environment recovery, not an external transport retry. Do not mutate the command, parameters, endpoint, or acquisition surface while requesting access.\n4. If access is declined or no permission mechanism is available, state only that the required network access was not granted and the task could not continue. Do not label endpoints as failed or imply that API requests consumed credits when no request reached the service.\n5. After the permission issue is resolved, classify the rerun normally through the sections below. Do not use this gate to bypass a returned HTTP status, credential failure, credit failure, validation failure, rate limit, or confirmed service outage.\n\n## Result acquisition\n\n1. Always inspect stdout, even when the process exits non-zero. Exit `1` with valid structured JSON means at least one API call failed; it does not make the JSON unreadable.\n2. Treat `_transport.status` as the authoritative outer HTTP status. Response-body or nested status-like fields never override it.\n3. For a composite payload, inspect nested endpoint results before classifying the whole workflow. Preserve returned `_query`, credit metadata, successful sections, and failure details internally.\n\n## Classification order\n\nAfter the execution-environment permission gate is resolved or found inapplicable, apply these routes in order:\n\n1. Missing credentials before an evidence call follow the local skill's missing-key procedure.\n2. `_transport.status=401` and `_transport.status=402` follow the local skill's credential and credit procedures. Do not retry, switch endpoints, or change credential sources.\n3. `_transport.status=422` is validation failure. Preserve the structured server error and `_query.params`; do not retry the unchanged request. Correct only fields identified by the server contract.\n4. A terminal interface failure is present when the result carries `error.action=\"STOP_CURRENT_TURN. APPLY_SKILL_INTERFACE_FAILURE_TEMPLATE. DO_NOT_SELECT_ANOTHER_COMMAND.\"`, or represents exhausted HTTP 5xx, exhausted 429, exhausted non-HTTP transport failure after host permission restrictions have been ruled out or resolved, endpoint unavailability, `MALFORMED_RESPONSE`, or non-zero execution without valid structured JSON.\n5. A valid `status=empty` or a documented business/coverage error is not automatically terminal. A local skill fallback is allowed only when its contract explicitly supports that result and no terminal interface-failure signal is present.\n\n## Retry and terminal behavior\n\nThe shared CLI owns transport retries. Once the execution-environment permission gate is resolved or found inapplicable, a terminal interface failure requires:\n\n1. Stop the current workflow turn. Do not retry externally, mutate parameters, switch endpoints or acquisition surfaces, start another tool command, or continue to a later workflow step.\n2. Do not reinterpret an HTTP 5xx body as validation, credential, credit, empty coverage, or permission to try another date, subject, marketplace, filter, or page.\n3. Retain earlier successful data for compatible later reuse, but do not produce the normal analysis, update monitoring/baseline state, or request the next workflow input.\n4. Keep detailed messages, request parameters, retry logs, and control tokens internal unless the user explicitly requests diagnostics.\n5. Hand off rendering to the active skill's local interface-failure template. This shared contract intentionally defines no user-facing wording.\n\n## Composite and partial results\n\n- A non-zero composite result may still contain successful sections. If any nested result is a terminal interface failure, stop after inventorying succeeded and failed interfaces; do not turn the surviving sections into the normal conclusion.\n- If all failures are documented non-terminal business/coverage failures, a local skill may use its explicit fallback and the compatible successful sections. Label coverage precisely and never present the composite as fully successful.\n- Process exit status and JSON status must agree for a single-result command. A partial pagination failure must return `success=false` while preserving already collected rows under `data`.\n\n## Realtime unavailable — offline fallback\n\n`realtime/product` is a live scrape endpoint that can return a transient 200-success with an empty payload. Composites retry it a few times; if it is still empty, that item's result carries `_realtimeStatus=\"empty_after_retries\"`, and the composite `meta` carries `realtimeUnavailable` (count) plus `realtimeFallbackHint`. When `realtimeFallbackHint` is present, tell the user realtime lookup is temporarily unavailable for those items, then continue the analysis using the offline snapshot data already gathered (products/search fields, history, price/BSR/rating). Do not stall, silently re-run, or fabricate the missing realtime detail.\n\n## Partial review pagination\n\nWhen `reviews-raw` fails after one or more successful pages, it returns `success=false`, preserves collected reviews and page count under `data`, and exposes the failed page request through `_failedQuery`. Never treat that payload as a complete review sample.\n\nFile v1.1.9:references/reference.md\n\n# ZooData API Field Reference\n\n> Load this file only when you need exact field names or response structure.\n\n## ZooData Endpoint Field Reference\n\n> Shared field reference. This skill's workflows use ONLY the subcommands\n> listed in its SKILL.md; the endpoints below are documented for field-name /\n> response-structure lookup, not as a claim that this skill invokes all of them.\n\n| # | Endpoint | Purpose |\n|---|----------|---------|\n| 1 | `categories` | Category path lookup |\n| 2 | `markets/search` | Market size, competition metrics, new-product rate |\n| 3 | `products/search` | Product supply (100+ via pagination), brand/price drill |\n| 4 | `products/competitors` | Top competitor list |\n| 5 | `realtime/product` | Live product detail |\n| 6 | `reviews/analysis` | Consumer pain points, buying factors |\n| 7 | `products/price-band-overview` | Price-band opportunity overview |\n| 8 | `products/price-band-detail` | Per-band SKU/sales/brand/rating breakdown |\n| 9 | `products/brand-overview` | Brand count, CR10, top-brand avg price/rating |\n| 10 | `products/brand-detail` | Per-brand SKU/sales/revenue/share ranking |\n| 11 | `products/history` | 30-day price/BSR/sales trend |\n\nBase URL: `https://api.zoodata.ai/openapi/v2`\nAuth: `Bearer $ZOODATA_API_KEY`\nMethod: All POST with JSON body\nAll endpoints return: `{success, data, error, meta}` with `meta.creditsRemaining`\n\n---\n\n## 1. categories\n\n**Request:** (mutually exclusive modes)\n- No params → root categories\n- `categoryKeyword`: String → search by keyword\n- `categoryPath`: List<String> → exact path\n- `parentCategoryPath`: List<String> → child categories\n\n**Response:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `categoryId` | string | Category ID |\n| `categoryName` | string | Category name |\n| `categoryPath` | list | Full path from root |\n| `hasChildren` | bool | Has subcategories |\n| `level` | int | Depth (1=root) |\n| `productCount` | int | Products in category |\n\n---\n\n## 2. markets/search\n\n**Key Request Params:**\n- `categoryPath`: List<String> (e.g. `[\"Pet Supplies\", \"Dogs\"]`)\n- `categoryKeyword`: String\n- `topN`: **String** (`\"10\"` not `10`)\n- `sampleType`: `by_sale_100` / `by_bsr_100` / `avg`\n- `pageSize`: Integer (max 20)\n\n**Key Response Fields:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `totalSkuCount` | int | Market size |\n| `sampleAvgMonthlySales` | float | Demand level |\n| `sampleAvgMonthlyRevenue` | float | Market value |\n| `sampleAvgPrice` | float | Price benchmark |\n| `sampleAvgRating` | float | Quality benchmark |\n| `sampleBrandCount` | int | Brand diversity |\n| `sampleSellerCount` | int | Seller diversity |\n| `sampleFbaRate` | float | FBA adoption (decimal) |\n| `sampleNewSkuRate` | float | New entrant rate (decimal) |\n| `topSalesRate` | float | Product concentration (CR_topN) |\n| `topBrandSalesRate` | float | Brand concentration |\n| `topSellerSalesRate` | float | Seller concentration |\n| `sampleAPlusRate` | float | Margin benchmark |\n\n---\n\n## 3. products/search — Shared Product Object\n\n**Key Request Params:**\n- `keyword`, `categoryPath`, `keywordMatchType` (`mode` is a CLI-only preset — `zoodata.py` expands it into the filter pairs below client-side; it is NOT an API field and returns 422 if sent raw)\n- Filter pairs: `monthlySalesMin/Max`, `priceMin/Max`, `ratingMin/Max`, etc.\n- `pageSize` (max 20), `page`, `sortBy`, `sortOrder`\n- `includeBrands`, `excludeBrands`\n\n**Key Response Fields (per product):**\n| Field | Type | Used For |\n|-------|------|----------|\n| `asin` | string | Product ID |\n| `title` | string | Product name |\n| `brandName` | string | Brand |\n| `price` | float | Price |\n| `monthlySalesFloor` | int | Monthly sales (lower bound) |\n| `monthlyRevenueFloor` | float | Monthly revenue lower bound |\n| `rating` | float | Rating (0-5) |\n| `ratingCount` | int | Review count |\n| `bsr` | int | BSR (NOT `bestsellersRank`) |\n| `fbaFee` | float | FBA cost |\n| `sellerCount` | int | Sellers on listing |\n| `fulfillment` | string | FBA/FBM/AMZ |\n| `listingDate` | string | When listed |\n| `salesGrowthRate` | float | Growth rate |\n| `variantCount` | int | Variants |\n\n---\n\n## 4. products/competitors\n\nSame response as products/search. Different use: discovery by keyword/brand/asin.\nRequest params: `keyword`, `brand`, `asin`, `categoryPath`, `sortBy`, `pageSize`\n\n---\n\n## 5. realtime/product\n\n**Request:**\n- `asin`: String (required)\n- `marketplace`: String (US/UK/DE/FR/IT/ES/JP/CA/AU/IN/MX/BR, default US)\n\n**Response:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `asin` | string | Product ID |\n| `title` | string | Full title |\n| `brandName` | string | Brand |\n| `rating` | float | Current rating |\n| `ratingCount` | int | Current review count |\n| `ratingBreakdown` | object | Star distribution {five_star: {percentage, count}, ...} |\n| `features` | list | Bullet points |\n| `description` | string | Product description |\n| `specifications` | object | Tech specs |\n| `variants` | list | All variants with dimensions |\n| `bestsellersRank` | list | BSR info [{category, rank}, ...] |\n| `buyboxWinner` | object | Buy Box: {price, fulfillment, seller} |\n| `images` | list | All image URLs |\n\n⚠️ Does NOT have: monthlySalesFloor, fbaFee, sellerCount\n\n---\n\n## 6. reviews/analysis\n\n**Request:**\n- `mode`: `\"asin\"` or `\"category\"`\n- `asins`: List<String> (when mode=asin)\n- `categoryPath`: String (when mode=category)\n- `labelType`: filter to specific dimensions. **⚠️ Only ONE value per call — do NOT comma-separate multiple types.** Make separate calls for each labelType needed.\n- `period`: e.g. `\"1m\"` / `\"3m\"` / `\"6m\"` / `\"1y\"` / `\"2y\"`\n\n**labelType values (one per call):** `scenarios`, `issues`, `positives`, `improvements`, `buyingFactors`, `painPoints`, `keywords`, `userProfiles`, `usageTimes`, `usageLocations`, `behaviors`\n\n**Response:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `reviewCount` | int | Sample size |\n| `avgRating` | float | Overall satisfaction |\n| `sentimentDistribution` | object | Positive/neutral/negative ratio |\n| `consumerInsights` | list | Structured insights by dimension |\n| `topKeywords` | list | Trending terms |\n\n**InsightItem:** `{element, labelType, count, reviewRate, avgRating}`\n\n---\n\n## 7. products/price-band-overview\n\n**Request:** Same params as products/search (keyword, category, filters)\n\n**Response:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `sampleSkuCount` | int | Total products analyzed |\n| `sampleMedianPrice` | float | Median price point |\n| `hottestBand` | object | Highest sales share band |\n| `bestOpportunityBand` | object | Highest opportunity index band |\n\n**Band object:** `{bandIdx, bandLabel, sampleBandMinPrice, sampleBandMaxPrice, sampleSkuCount, sampleSalesRate, sampleBrandCount, sampleTop3BrandSalesRate, sampleAvgRating, sampleOpportunityIndex}`\n\n---\n\n## 8. products/price-band-detail\n\n**Response:**\n- `sampleSkuCount`, `sampleTotalMonthlySales`\n- `priceBands`: array of 5 band objects (same structure as above)\n\n---\n\n## 9. products/brand-overview\n\n**Response:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `sampleBrandCount` | int | Total brands |\n| `sampleTop10BrandSalesRate` | float | CR10 concentration (top 10 brands) |\n| `sampleTop10AvgRating` | float | Top 10 brand avg rating |\n| `sampleTop10AvgPrice` | float | Top 10 brand avg price |\n\n---\n\n## 10. products/brand-detail\n\n**Response:**\n- `sampleSkuCount`, `sampleTotalMonthlySales`, `sampleBrandCount`\n- `brands`: array of brand objects\n\n**BrandStats:** `{brandName, sampleSkuCount, sampleGroupMonthlySales, sampleGroupMonthlyRevenue, sampleSalesRate, sampleAvgPrice, minPrice, maxPrice, sampleAvgRating, sampleAvgRatingCount, sampleProducts}`\n\n**sampleProducts:** List of Product objects for this brand within the sample. Each product contains the full Shared Product Object fields (asin, title, price, bsr, monthlySalesFloor, rating, ratingCount, fulfillment, etc). This enables brand-level product matrix analysis without a separate products/search call.\n\n---\n\n## 11. products/history\n\n**Request:**\n- `asins`: List<String> (required)\n- `startDate`: String \"YYYY-MM-DD\" (required)\n- `endDate`: String \"YYYY-MM-DD\" (required)\n⚠️ Does NOT accept `dateRange` — must use startDate + endDate\n\n**Response (array of daily snapshots):**\n| Field | Type | Used For |\n|-------|------|----------|\n| `asin` | string | Product ID |\n| `price` | float | Price on that day |\n| `bsr` | int | BSR on that day |\n| `subBsr` | int | Sub-category BSR |\n| `recentSales` | int | Recent sales count |\n| `updatedAt` | string | Unix timestamp (string) |\n| `createdAt` | string | Unix timestamp (string) |\n\n---\n\n## Cross-Validation Matrix\n\n| Data Point | Primary Source | Validation Source |\n|-----------|---------------|-------------------|\n| Market size | markets/search | products/search (total count) |\n| Brand concentration | brand-overview (sampleTop10BrandSalesRate) | markets/search (topBrandSalesRate) |\n| Price distribution | price-band-detail | products/search (price field) |\n| Competition level | markets (topSalesRate) | brand-detail (top brand shares) |\n| Consumer demand | reviews/analysis | products (sales + growth) |\n| Avg rating quality | markets (sampleAvgRating) | brand-overview (sampleTop10AvgRating) |\n\nFile v1.1.9:scripts/allowed-commands.json\n\n{\n  \"allowedCommands\": [\n    \"analyze\",\n    \"categories\",\n    \"check\",\n    \"competitor-analysis\",\n    \"competitors\",\n    \"history\",\n    \"market\",\n    \"product\",\n    \"products\",\n    \"review-aggregate\",\n    \"review-reduce-prompt\",\n    \"review-tag-prompt\",\n    \"reviews-raw\"\n  ]\n}\n\nFile v1.1.9:skill-card.md\n\n## Description:\n\nAnalyzes defined Amazon competitor sets with ZooData, producing full competitive teardowns or recurring Quick Check monitoring alerts.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[apiclaw](https://clawhub.ai/user/apiclaw)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal sellers, marketplace analysts, and agents use this skill to analyze identified Amazon competitors by keyword, ASIN, or brand and to monitor tracked competitors for price, inventory, rating, and listing changes.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The ZooData API key can be redirected through ZOODATA_BASE_URL, including to HTTP or localhost according to the security summary.\n\nMitigation: Leave ZOODATA_BASE_URL unset unless a reviewed ZooData endpoint is required; do not point it at HTTP, localhost, or unofficial hosts.\n\nRisk: The published install command is unpinned.\n\nMitigation: Prefer a pinned install source or reviewed commit before deployment.\n\nRisk: Scheduled monitoring stores local baseline and history data and consumes API credits on recurring runs.\n\nMitigation: Enable scheduled monitoring only after explicit confirmation, monitor credit usage, and delete monitor-data when retained state is no longer needed.\n\nRisk: Runs send ASINs, competitor ASINs, keywords, category paths, and marketplace/date/numeric filters to ZooData.\n\nMitigation: Use the skill only with data that is acceptable to send to ZooData and avoid entering unrelated profile or account details.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/apiclaw/skills/amazon-competitor-intelligence-monitor)\n- [Publisher Profile](https://clawhub.ai/user/apiclaw)\n- [ZooData Skills Repository](https://github.com/SerendipityOneInc/ZooData-Skills)\n- [ZooData API Field Reference](references/reference.md)\n- [ZooData CLI Contract](references/cli-contract.md)\n- [ZooData API](https://api.zoodata.ai/openapi/v2)\n- [ZooData](https://zoodata.ai)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown reports with tables, structured API provenance, alert summaries, and setup commands.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Requires ZOODATA_API_KEY and may create local monitor-data state for baselines, history, and alerts.]\n\n## Skill Version(s):\n\n1.1.9 (source: SKILL.md frontmatter and release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.1.8: 7 files, 54537 bytes\n\nFiles: README.md (3145b), references/cli-contract.md (8636b), references/reference.md (9267b), scripts/zoodata.py (175180b), skill-card.md (2762b), SKILL.md (15450b), _meta.json (157b)\n\nFile v1.1.8:SKILL.md\n\n---\nname: amazon-competitor-intelligence-monitor\ndescription: >\n  Amazon competitor intelligence engine. Produces analytical output focused on\n  a defined set of competitors: either a one-shot deep teardown (Full Scan:\n  28-35 credits, 11 endpoints, battle card, side-by-side comparison,\n  pricing/review/inventory breakdown) OR sustained per-competitor monitoring\n  with alerts (Quick Check: 5-10 credits, realtime polling, baseline diff).\n  Input: keyword, ASIN(s), or brand — whatever identifies the competitor set\n  to analyze. Output is per-competitor analytical insight tied to that\n  specific set.\n  Use when the user wants focused analysis on identified competitors:\n  a one-shot teardown or an ongoing per-competitor watch.\n  Use when user asks: analyze competitor B07XXX, battle card for ASIN Y,\n  side-by-side competitor teardown, spy on a brand, deep analysis of these\n  3 competitors, ongoing watch on a defined competitor set.\n  Requires ZOODATA_API_KEY.\nmetadata:\n  version: \"1.1.8\"\n  author: SerendipityOneInc\n  homepage: https://github.com/SerendipityOneInc/ZooData-Skills\n  openclaw: {\"requires\": {\"env\": [\"ZOODATA_API_KEY\"]}, \"primaryEnv\": \"ZOODATA_API_KEY\"}\n---\n\n# ZooData — Competitor Intelligence Monitor\n\n> Know your enemy. Two modes: Full Scan + Quick Check. Respond in user's language.\n\n## Files\n\n| File | Purpose |\n|------|---------|\n| `{skill_base_dir}/scripts/zoodata.py` | **Execute** for all API calls (run `--help` for params) |\n| `{skill_base_dir}/references/reference.md` | Load for exact field names or response structure |\n| `{skill_base_dir}/monitor-data/` | Runtime storage (auto-created): config.json, baseline.json, history/, alerts.json |\n\n## Credential\n\nRequired: `ZOODATA_API_KEY`. Get free key at [zoodata.ai/api-keys](https://zoodata.ai/en/api-keys).\n\n## Capabilities & Data Flow\n\n- **Network**: only `https://api.zoodata.ai` (Bearer `ZOODATA_API_KEY`). Setting `ZOODATA_BASE_URL` to an untrusted host (anything other than `api.zoodata.ai` / `*.zoodata.ai` / localhost) makes the CLI **refuse the request and withhold the key** — the Bearer token is never sent to an untrusted host.\n- **Execution**: bundled shared ZooData CLI `{skill_base_dir}/scripts/zoodata.py` (Python 3, stdlib-only). This skill allows `categories`, `market`, `competitors`, `products`, `product`, `history`, `analyze`, `competitor-analysis`, `check`, plus the review fallback toolkit (`reviews-raw` / `review-tag-prompt` / `review-reduce-prompt` / `review-aggregate`). Do not invoke unrelated subcommands for this skill's tasks.\n- **Local files**: a temporary `/tmp/review_<ASIN>_<timestamp>/` working dir during the review fallback; reads the optional credential store `~/.zoodata/config.json`.\n- **Sent to the API**: keywords, category paths, ASINs, marketplace/date and numeric filter values only. **Never sent**: budget, experience level, risk tolerance, or any other user-profile text — profile inputs map client-side to numeric filters.\n- **Credits**: every API call consumes account credits. For broad or ambiguous requests, state the estimated credit cost and confirm with the user before running multi-call scans. The composite `competitor-analysis` command executes ~17+ API calls (Full Scan, ~28-35 credits documented) in ONE invocation and has NO skip/trim flags — under a credit cap, use the granular commands instead.\n\n## Shared CLI Contract\n\nBefore selecting or invoking the first command, read and apply the local `references/cli-contract.md`. Reapply it after every granular or composite result and before any fallback, additional call, state write, interpretation, or user-facing report. Use this skill's fallback logic only when the shared contract classifies the result as non-terminal.\n\n### Local Interface Failure Output\n\nFor a terminal interface failure, respond in the user's language that the competitor scan could not be completed, then list succeeded and failed endpoint identifiers. Do not emit a battle card, threat score, alert, monitoring recommendation, or baseline update. Keep control tokens, parameters, and retry logs internal unless diagnostics are requested.\n\n## Input\n\nRequired: keyword or ASIN(s). Optional: my_asin, competitor_asins, brand.\nIf only ASIN given → derive keyword via `product --asin` then ask user to confirm.\nBrand queries MUST also include confirmed `--category`.\n\n## API Pitfalls (CRITICAL)\n\n1. **Category auto-detection**: categoryPath is auto-detected from keyword, ASIN, or top search result. If `category_source` in output is `inferred_from_search`, MUST confirm with user before trusting results\n2. **All keyword-based endpoints MUST include `--category`**; ASIN-specific endpoints do NOT need it\n3. **Brand + category**: a brand sells across categories — only analyze within locked subcategory\n4. **Use API fields directly**: revenue=`sampleAvgMonthlyRevenue` (NEVER price×sales), sales=`monthlySalesFloor`, concentration=`sampleTop10BrandSalesRate`\n5. **reviews/analysis**: needs 50+ reviews. Fallback chain when sample is insufficient:\n   1. **Lightweight**: `realtime/product` ratingBreakdown — only star distribution, no themes\n   2. **Full 11-dim insights** — bypass `/reviews/analysis` entirely:\n      a. `zoodata.py reviews-raw --asin X` → fetch up to 100 raw reviews (10 credits, ~60s)\n      b. For each review: render Map prompt via `zoodata.py review-tag-prompt --review '<json>'`\n         and have your own LLM produce JSON tags (sentiment + 11 dimensions)\n      c. Collect candidate phrases per dimension; for each dimension render\n         Reduce prompt via `zoodata.py review-reduce-prompt --label-type X --candidates '[...]'`\n         and have your LLM produce semantic clusters\n      d. `zoodata.py review-aggregate --reviews R --tagged T --clusters C`\n         → consumerInsights output compatible with `/reviews/analysis`\n   3. **Fallback caveats** (apply to the 4-step chain above — lessons from end-to-end validation):\n      - **Working dir**: `WORK=/tmp/review_<ASIN>_$(date +%s) && mkdir -p $WORK`\n      - **Step b CLI behavior**: `review-tag-prompt` RENDERS the prompt only; YOUR LLM produces the JSON. Render once to learn the schema, then produce tags for all N reviews in one in-context pass (don't call the CLI N times).\n      - **Step c candidate extraction** (Python one-liner):\n        `candidates = {d: sorted({el.strip().lower() for t in tagged for el in (t.get(d) or [])}) for d in DIMS}`\n      - **Small-sample rule (reviewCount<50)**: demote single-mention items 📊→🔍; NEVER attach table-level or section-header 📊 when any row inside is 🔍; suppress \"🔴 Critical\" verdicts on count=1\n      - **Scope**: fallback replaces ONLY the `/reviews/analysis` aggregation. This skill's primary workflow outputs (competitor metrics, brand ranking, pricing, etc.) remain valid — do not re-run them.\n\n## On Missing Key\n\nWhen `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`), stop before any evidence call. Tell the user that a ZooData API key is required, link to https://zoodata.ai/en/api-keys, and explain that the key may be set in the environment or local config. Do not substitute public knowledge or a \"for reference only\" analysis.\n## On 401 Invalid Key\n\nWhen `_transport.status=401`, stop further calls, tell the user that the configured key was rejected, direct them to https://zoodata.ai/en/api-keys, and do not fabricate missing data.\n\n## On 402 Credit Exhausted\n\nWhen `_transport.status=402`, stop further calls. Report where the workflow stopped, any compatible partial findings already gathered, and returned credit metadata when present; direct the user to https://zoodata.ai/en/pricing and do not fabricate missing data.\n\n## Mode Selection\n\n- **Full Scan** (~28-35 credits): First run, no baseline.json, explicit request, or weekly refresh\n- **Quick Check** (~5-10 credits): Cron trigger, baseline exists, \"check competitors\"\n\n## Full Scan Flow\n\n1. `competitor-analysis --keyword X [--category Y] [--my-asin Z]` (composite, auto-detects category)\n2. If `category_source` is `inferred_from_search`, confirm with user before presenting results\n3. Analyze & score → save baseline to `{skill_base_dir}/monitor-data/` → offer Auto-Monitor\n\n## Quick Check Flow\n\n1. Load config.json + baseline.json from `{skill_base_dir}/monitor-data/` (missing → fall back to Full Scan)\n2. Poll `product --asin {asin}` for each tracked ASIN\n3. Diff against baseline with tiered alerts → update baseline → offer Auto-Monitor\n\n## Alert Tiers\n\n| 🔴 Critical | 🟡 Watch | 🟢 Opportunity |\n|-------------|----------|----------------|\n| Price change > threshold | FBA↔FBM switch | Competitor stock-out |\n| BSR crash > threshold | Rating change | Bullet/image changes |\n| Buy Box owner changed | Abnormal review growth | Variant added/removed |\n| | Title modified | |\n\n## Competitive Score (per competitor, 1-100)\n\n| Dimension | Weight | 80-100 (Strong) | 50-79 (Moderate) | 0-49 (Weak) |\n|-----------|--------|-----------------|-------------------|-------------|\n| Sales Dominance | 25% | Top 3 in category, >5K units/mo 📊 | Top 20, 1K-5K units/mo 📊 | Below Top 20, <1K units/mo 📊 |\n| Brand Strength | 20% | Brand in CR10, 5+ SKUs, wide price range 📊 | Known brand, 2-4 SKUs 📊 | Unknown brand, single SKU 📊 |\n| Listing Quality | 20% | 7+ images, 5 bullets, A+, optimized title 📊 | 5-6 images, basic bullets 📊 | <5 images, weak bullets, no A+ 📊 |\n| Customer Satisfaction | 20% | Rating ≥4.5, <3% 1-star, positive sentiment 📊 | 4.0-4.4, 3-8% 1-star 📊 | <4.0 or >8% 1-star 📊 |\n| Trend Momentum | 15% | BSR improving 30d, sales growth >10% 🔍 | BSR stable, flat sales 🔍 | BSR declining, sales drop 🔍 |\n\n### Competitive Threat Level\n| Total Score | Threat | Interpretation |\n|-------------|--------|---------------|\n| 80-100 | 🔴 Dominant | Hard to compete head-on; find differentiation or avoid price band 💡 |\n| 50-79 | 🟡 Competitive | Beatable with better listing, pricing, or reviews 💡 |\n| 0-49 | 🟢 Vulnerable | Weak competitor; opportunity to capture share 💡 |\n\n### Market Structure Analysis\n- **CR10 > 70%**: Concentrated market — new entrants need strong differentiation or niche positioning 🔍\n- **CR10 40-70%**: Moderately competitive — room for well-positioned products 🔍\n- **CR10 < 40%**: Fragmented — opportunity for brand building 🔍\n- **Top brand share > 25%**: Category leader dominance — avoid direct competition in their price band 💡\n- **New SKU rate > 15%**: Active market with frequent new entrants 📊\n- **New SKU rate < 5%**: Mature/stagnant market, high barriers 🔍\n\n## Auto-Monitor Prompt\n\nAfter EVERY run, offer: \"Set up automatic monitoring? I can generate a scheduled Quick Check.\" Provide platform-specific setup (OpenClaw `/cron`, ChatGPT Scheduled Tasks, Claude Projects).\n\n## Output Spec\n\nFull Scan sections: Battlefield Overview → Competitor Matrix → Brand Power Ranking → Price Map → 30-Day Trends → Review Battle → Listing Audit → Competitive Scores → Battle Strategy → Data Provenance → API Usage.\n\n### Language (required)\n\nOutput 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.\n\n### Disclaimer (required, at the top of every report)\n\n> 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.\n\n### Confidence Labels (required, tag EVERY conclusion)\n\n- 📊 **Data-backed** — direct API data (e.g. \"CR10 = 54.8% 📊\")\n- 🔍 **Inferred** — logical reasoning from data (e.g. \"brand concentration is moderate 🔍\")\n- 💡 **Directional** — suggestions, predictions, strategy (e.g. \"consider entering $10-15 band 💡\")\n\nRules: Strategy recommendations are NEVER 📊. Anomalies (>200% growth) are always 💡. User criteria override AI judgment.\n\n**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:\n- Section headers at EVERY level (`#`, `##`, `###`, `####`) — including top-level summary sections like \"Overall Score\", \"Verdict\", \"Executive Summary\"\n- Summary/score lines anywhere in the report (e.g. `## Overall Score — 27/100 · Grade F 📊` is WRONG if any Basis row inside is 🔍)\n- Table **column** headers in comparison tables (e.g. `**Target ASIN** 📊` as a column label is WRONG if any cell in that column contains 🔍)\n- Table row headers or row-aggregation labels (when the row aggregates multiple cells of mixed confidence)\n- Any other visual grouping label — bullet-list group titles, callout box titles, etc.\n\nA 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.\n\n**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:\n- ❌ WRONG: `## 📊 Overall Score — 27/100 · Grade F 🔍` (the leading 📊 reads as a data-backed claim even though the trailing 🔍 is correct)\n- ✅ RIGHT: `## Overall Score — 27/100 · Grade F 🔍` (no decorative emoji, just the proper confidence suffix)\n- ✅ RIGHT: `## 🎯 Overall Score — 27/100 · Grade F 🔍` (use non-reserved decorative icons like 🎯 🧭 📋 📝 📂 🏁 🚨 🏆 🔔 when a visual prefix is desired)\n\nDecorative 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.\n\n### Data Provenance (required)\n\nInclude a table at the end of every report:\n\n| Data | Endpoint | Key Params | Notes |\n|------|----------|------------|-------|\n| (e.g. Market Overview) | `markets/search` | categoryPath, topN=10 | 📊 Top N sampling, sales are lower-bound |\n| ... | ... | ... | ... |\n\nExtract endpoint and params from `_query` in JSON output. Add notes: sampling method, T+1 delay, realtime vs DB, minimum review threshold, etc.\n\n### API Usage (required)\n\n| Endpoint | Calls | Credits |\n|----------|-------|---------|\n| (each endpoint used) | N | N |\n| **Total** | **N** | **N** |\n\nExtract from `meta.creditsConsumed` per response. End with `Credits remaining: N`.\n\n## API Budget\n\nFull Scan: ~28-35 credits (all 11 endpoints via composite). Quick Check: ~5-10 credits (realtime/product × N ASINs).\n\nFile v1.1.8:README.md\n\n# Amazon Competitor Intelligence Monitor — ZooData Agent Skill\n\n> Know your enemy. Full Scan + Quick Check. Always watching.\n\n## What This Skill Does\n\nDeep competitor intelligence with two operational modes. **Full Scan** delivers a complete competitive landscape — competitor matrix, brand ranking, pricing map, review battle, and battle strategy. **Quick Check** polls tracked ASINs against a saved baseline and fires tiered alerts when something changes.\n\n### What Makes This Different\n\n- **Dual-mode**: Full Scan (~28-35 credits) for deep analysis, Quick Check (~5-10 credits) for lightweight monitoring\n- **Three-tier alerts**: 🔴 Critical (price crash, Buy Box lost), 🟡 Watch (FBA switch, rating shift), 🟢 Opportunity (stock-out, listing changes)\n- **Competitive Score**: Each competitor scored 1-100 across 5 dimensions (sales, brand, listing, satisfaction, trend)\n- **Auto-Monitor**: Offers scheduled Quick Check setup after every run\n\n## Install\n\n```bash\nnpx skills add SerendipityOneInc/ZooData-Skills\n```\n\nSelect **Amazon Competitor Intelligence Monitor** when prompted.\n\n## API Key Setup\n\n1. Get a free key at [zoodata.ai/api-keys](https://zoodata.ai/en/api-keys) — 1,000 free credits, no credit card\n2. Set the environment variable:\n   ```bash\n   export ZOODATA_API_KEY='hms_live_xxxxxx'\n   ```\n\n## Example Prompts\n\n- *\"Analyze my competitors for ASIN B0XXXXXXXX in the yoga mat market\"*\n- *\"Run a full competitor scan for keyword 'silicone spatula'\"*\n- *\"Quick check my tracked competitors\"*\n- *\"Who are the top competitors for 'dog harness' and how do I beat them?\"*\n- *\"Monitor competitor price changes and alert me on anomalies\"*\n\n## What You Get\n\n| Section | Description |\n|---------|-------------|\n| ⚔️ Battlefield Overview | Market size, player count, concentration |\n| 📊 Competitor Matrix | Side-by-side comparison of all key competitors |\n| 🏅 Brand Power Ranking | Brand strength scores and market share |\n| 💰 Price Map | Price positioning across competitors |\n| 📈 30-Day Trends | BSR, price, and sales movement |\n| 💬 Review Battle | Rating, sentiment, pain points per competitor |\n| 📋 Listing Audit | Image, bullet, A+ content comparison |\n| 🎯 Battle Strategy | Actionable recommendations to outperform |\n| 🚨 Alerts (Quick Check) | Tiered change detection vs baseline |\n\n## API Endpoints Used\n\n| Endpoint | Purpose |\n|----------|---------|\n| `categories` | Category resolution |\n| `markets/search` | Market context |\n| `products/search` | Product landscape |\n| `products/competitors` | Competitor discovery |\n| `realtime/product` | Live competitor data |\n| `reviews/analysis` | Sentiment & pain points |\n| `products/price-band-overview` | Price band context |\n| `products/price-band-detail` | Detailed price analysis |\n| `products/brand-overview` | Brand concentration |\n| `products/brand-detail` | Per-brand breakdown |\n| `products/history` | Trend analysis |\n\n## Credit Cost\n\nFull Scan: ~28-35 credits. Quick Check: ~5-10 credits.\n\n## Powered By\n\n[ZooData](https://zoodata.ai) — The data infrastructure built for agents. 200M+ Amazon products, 1B+ reviews, real-time signals.\n\nFile v1.1.8:_meta.json\n\n{\n  \"ownerId\": \"kn78k155f6rbh2j8r8yjx8r2e18304q9\",\n  \"slug\": \"amazon-competitor-intelligence-monitor\",\n  \"version\": \"1.1.8\",\n  \"publishedAt\": 1785806905495\n}\n\nFile v1.1.8:references/cli-contract.md\n\n<!-- Canonical source - do not edit copies under amazon-* skill directories directly -->\n\n# ZooData CLI Contract\n\n## Ownership and application\n\nThis file owns the project-wide caller contract before and after every bundled `{skill_base_dir}/scripts/zoodata.py` invocation. Read it before selecting the first command, then apply it after each granular or composite result and before any additional API/tool call, fallback, state write, interpretation, or user-facing report.\n\nIt owns the shared invocation form, command-identity validation, execution-environment permission handling, caller/CLI responsibilities, composite-result reuse, result acquisition, transport-status precedence, terminal-interface classification, retry ownership, and partial-result handling. It does not own skill-specific command allowlists, endpoint request/response fields, business interpretation, scenario selection, conclusion authority, or any user-facing failure/report rendering.\n\n## Invocation interface\n\n1. Invoke the bundled client as `python {skill_base_dir}/scripts/zoodata.py [global options] <subcommand> [subcommand options]` using the active skill's local copy.\n2. Place global options before the subcommand. Treat top-level and subcommand `--help` as the live invocation contract; help inspection makes no API request and consumes no credits.\n3. Use the active skill to select the allowed workflow and command scope. Use this contract to validate and execute that selection; do not let this shared file select a business workflow.\n4. Distinguish API/evidence commands from local-only diagnostic, prompt-rendering, and aggregation commands according to the selected subcommand's help. Do not attribute an API call or credit use to a local-only command.\n5. Credential resolution is owned by the bundled CLI. Invoke it directly; do not inspect local credential stores or pre-resolve, compare, export, or override credential values in the caller.\n\n## Command identity and composite reuse\n\n1. Inspect the bundled CLI's top-level `--help` and the selected subcommand's `--help` before invocation. Execute only an exact literal subcommand exposed by the current client and allowed by the active skill.\n2. Treat API endpoint identifiers and composite result keys as data identities, not CLI command names. Never derive a subcommand from either identity or invent an alias.\n3. Treat a successful composite command's structured output as the evidence bundle for that run. Perform selection, narrowing, transformation, extraction, and formatting locally.\n4. Do not make an additional API call solely to reread, reshape, or narrow evidence already present in the composite bundle.\n5. A granular call after a composite is allowed only for evidence absent from the bundle when the active skill's workflow or an explicit non-terminal fallback requires it.\n\n## Execution-environment permission gate\n\nApply this gate before classifying a connection or network failure as a CLI/API interface failure.\n\n1. Inspect the execution tool's permission profile and diagnostics. When they indicate, or strongly suggest, that a host sandbox or network policy blocked the request, treat the result as unresolved execution permission rather than endpoint failure.\n2. Use the execution tool's permission or escalation mechanism to request access and rerun the exact unchanged CLI command. Do not first emit the skill's interface-failure notice or a succeeded/failed endpoint ledger.\n3. A permission-approved rerun is environment recovery, not an external transport retry. Do not mutate the command, parameters, endpoint, or acquisition surface while requesting access.\n4. If access is declined or no permission mechanism is available, state only that the required network access was not granted and the task could not continue. Do not label endpoints as failed or imply that API requests consumed credits when no request reached the service.\n5. After the permission issue is resolved, classify the rerun normally through the sections below. Do not use this gate to bypass a returned HTTP status, credential failure, credit failure, validation failure, rate limit, or confirmed service outage.\n\n## Result acquisition\n\n1. Always inspect stdout, even when the process exits non-zero. Exit `1` with valid structured JSON means at least one API call failed; it does not make the JSON unreadable.\n2. Treat `_transport.status` as the authoritative outer HTTP status. Response-body or nested status-like fields never override it.\n3. For a composite payload, inspect nested endpoint results before classifying the whole workflow. Preserve returned `_query`, credit metadata, successful sections, and failure details internally.\n\n## Classification order\n\nAfter the execution-environment permission gate is resolved or found inapplicable, apply these routes in order:\n\n1. Missing credentials before an evidence call follow the local skill's missing-key procedure.\n2. `_transport.status=401` and `_transport.status=402` follow the local skill's credential and credit procedures. Do not retry, switch endpoints, or change credential sources.\n3. `_transport.status=422` is validation failure. Preserve the structured server error and `_query.params`; do not retry the unchanged request. Correct only fields identified by the server contract.\n4. A terminal interface failure is present when the result carries `error.action=\"STOP_CURRENT_TURN. APPLY_SKILL_INTERFACE_FAILURE_TEMPLATE. DO_NOT_SELECT_ANOTHER_COMMAND.\"`, or represents exhausted HTTP 5xx, exhausted 429, exhausted non-HTTP transport failure after host permission restrictions have been ruled out or resolved, endpoint unavailability, `MALFORMED_RESPONSE`, or non-zero execution without valid structured JSON.\n5. A valid `status=empty` or a documented business/coverage error is not automatically terminal. A local skill fallback is allowed only when its contract explicitly supports that result and no terminal interface-failure signal is present.\n\n## Retry and terminal behavior\n\nThe shared CLI owns transport retries. Once the execution-environment permission gate is resolved or found inapplicable, a terminal interface failure requires:\n\n1. Stop the current workflow turn. Do not retry externally, mutate parameters, switch endpoints or acquisition surfaces, start another tool command, or continue to a later workflow step.\n2. Do not reinterpret an HTTP 5xx body as validation, credential, credit, empty coverage, or permission to try another date, subject, marketplace, filter, or page.\n3. Retain earlier successful data for compatible later reuse, but do not produce the normal analysis, update monitoring/baseline state, or request the next workflow input.\n4. Keep detailed messages, request parameters, retry logs, and control tokens internal unless the user explicitly requests diagnostics.\n5. Hand off rendering to the active skill's local interface-failure template. This shared contract intentionally defines no user-facing wording.\n\n## Composite and partial results\n\n- A non-zero composite result may still contain successful sections. If any nested result is a terminal interface failure, stop after inventorying succeeded and failed interfaces; do not turn the surviving sections into the normal conclusion.\n- If all failures are documented non-terminal business/coverage failures, a local skill may use its explicit fallback and the compatible successful sections. Label coverage precisely and never present the composite as fully successful.\n- Process exit status and JSON status must agree for a single-result command. A partial pagination failure must return `success=false` while preserving already collected rows under `data`.\n\n## Realtime unavailable — offline fallback\n\n`realtime/product` is a live scrape endpoint that can return a transient 200-success with an empty payload. Composites retry it a few times; if it is still empty, that item's result carries `_realtimeStatus=\"empty_after_retries\"`, and the composite `meta` carries `realtimeUnavailable` (count) plus `realtimeFallbackHint`. When `realtimeFallbackHint` is present, tell the user realtime lookup is temporarily unavailable for those items, then continue the analysis using the offline snapshot data already gathered (products/search fields, history, price/BSR/rating). Do not stall, silently re-run, or fabricate the missing realtime detail.\n\n## Partial review pagination\n\nWhen `reviews-raw` fails after one or more successful pages, it returns `success=false`, preserves collected reviews and page count under `data`, and exposes the failed page request through `_failedQuery`. Never treat that payload as a complete review sample.\n\nFile v1.1.8:references/reference.md\n\n# ZooData API Field Reference\n\n> Load this file only when you need exact field names or response structure.\n\n## ZooData Endpoint Field Reference\n\n> Shared field reference. This skill's workflows use ONLY the subcommands\n> listed in its SKILL.md; the endpoints below are documented for field-name /\n> response-structure lookup, not as a claim that this skill invokes all of them.\n\n| # | Endpoint | Purpose |\n|---|----------|---------|\n| 1 | `categories` | Category path lookup |\n| 2 | `markets/search` | Market size, competition metrics, new-product rate |\n| 3 | `products/search` | Product supply (100+ via pagination), brand/price drill |\n| 4 | `products/competitors` | Top competitor list |\n| 5 | `realtime/product` | Live product detail |\n| 6 | `reviews/analysis` | Consumer pain points, buying factors |\n| 7 | `products/price-band-overview` | Price-band opportunity overview |\n| 8 | `products/price-band-detail` | Per-band SKU/sales/brand/rating breakdown |\n| 9 | `products/brand-overview` | Brand count, CR10, top-brand avg price/rating |\n| 10 | `products/brand-detail` | Per-brand SKU/sales/revenue/share ranking |\n| 11 | `products/history` | 30-day price/BSR/sales trend |\n\nBase URL: `https://api.zoodata.ai/openapi/v2`\nAuth: `Bearer $ZOODATA_API_KEY`\nMethod: All POST with JSON body\nAll endpoints return: `{success, data, error, meta}` with `meta.creditsRemaining`\n\n---\n\n## 1. categories\n\n**Request:** (mutually exclusive modes)\n- No params → root categories\n- `categoryKeyword`: String → search by keyword\n- `categoryPath`: List<String> → exact path\n- `parentCategoryPath`: List<String> → child categories\n\n**Response:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `categoryId` | string | Category ID |\n| `categoryName` | string | Category name |\n| `categoryPath` | list | Full path from root |\n| `hasChildren` | bool | Has subcategories |\n| `level` | int | Depth (1=root) |\n| `productCount` | int | Products in category |\n\n---\n\n## 2. markets/search\n\n**Key Request Params:**\n- `categoryPath`: List<String> (e.g. `[\"Pet Supplies\", \"Dogs\"]`)\n- `categoryKeyword`: String\n- `topN`: **String** (`\"10\"` not `10`)\n- `sampleType`: `by_sale_100` / `by_bsr_100` / `avg`\n- `pageSize`: Integer (max 20)\n\n**Key Response Fields:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `totalSkuCount` | int | Market size |\n| `sampleAvgMonthlySales` | float | Demand level |\n| `sampleAvgMonthlyRevenue` | float | Market value |\n| `sampleAvgPrice` | float | Price benchmark |\n| `sampleAvgRating` | float | Quality benchmark |\n| `sampleBrandCount` | int | Brand diversity |\n| `sampleSellerCount` | int | Seller diversity |\n| `sampleFbaRate` | float | FBA adoption (decimal) |\n| `sampleNewSkuRate` | float | New entrant rate (decimal) |\n| `topSalesRate` | float | Product concentration (CR_topN) |\n| `topBrandSalesRate` | float | Brand concentration |\n| `topSellerSalesRate` | float | Seller concentration |\n| `sampleAPlusRate` | float | Margin benchmark |\n\n---\n\n## 3. products/search — Shared Product Object\n\n**Key Request Params:**\n- `keyword`, `categoryPath`, `keywordMatchType` (`mode` is a CLI-only preset — `zoodata.py` expands it into the filter pairs below client-side; it is NOT an API field and returns 422 if sent raw)\n- Filter pairs: `monthlySalesMin/Max`, `priceMin/Max`, `ratingMin/Max`, etc.\n- `pageSize` (max 20), `page`, `sortBy`, `sortOrder`\n- `includeBrands`, `excludeBrands`\n\n**Key Response Fields (per product):**\n| Field | Type | Used For |\n|-------|------|----------|\n| `asin` | string | Product ID |\n| `title` | string | Product name |\n| `brandName` | string | Brand |\n| `price` | float | Price |\n| `monthlySalesFloor` | int | Monthly sales (lower bound) |\n| `monthlyRevenueFloor` | float | Monthly revenue lower bound |\n| `rating` | float | Rating (0-5) |\n| `ratingCount` | int | Review count |\n| `bsr` | int | BSR (NOT `bestsellersRank`) |\n| `fbaFee` | float | FBA cost |\n| `sellerCount` | int | Sellers on listing |\n| `fulfillment` | string | FBA/FBM/AMZ |\n| `listingDate` | string | When listed |\n| `salesGrowthRate` | float | Growth rate |\n| `variantCount` | int | Variants |\n\n---\n\n## 4. products/competitors\n\nSame response as products/search. Different use: discovery by keyword/brand/asin.\nRequest params: `keyword`, `brand`, `asin`, `categoryPath`, `sortBy`, `pageSize`\n\n---\n\n## 5. realtime/product\n\n**Request:**\n- `asin`: String (required)\n- `marketplace`: String (US/UK/DE/FR/IT/ES/JP/CA/AU/IN/MX/BR, default US)\n\n**Response:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `asin` | string | Product ID |\n| `title` | string | Full title |\n| `brandName` | string | Brand |\n| `rating` | float | Current rating |\n| `ratingCount` | int | Current review count |\n| `ratingBreakdown` | object | Star distribution {five_star: {percentage, count}, ...} |\n| `features` | list | Bullet points |\n| `description` | string | Product description |\n| `specifications` | object | Tech specs |\n| `variants` | list | All variants with dimensions |\n| `bestsellersRank` | list | BSR info [{category, rank}, ...] |\n| `buyboxWinner` | object | Buy Box: {price, fulfillment, seller} |\n| `images` | list | All image URLs |\n\n⚠️ Does NOT have: monthlySalesFloor, fbaFee, sellerCount\n\n---\n\n## 6. reviews/analysis\n\n**Request:**\n- `mode`: `\"asin\"` or `\"category\"`\n- `asins`: List<String> (when mode=asin)\n- `categoryPath`: String (when mode=category)\n- `labelType`: filter to specific dimensions. **⚠️ Only ONE value per call — do NOT comma-separate multiple types.** Make separate calls for each labelType needed.\n- `period`: e.g. `\"1m\"` / `\"3m\"` / `\"6m\"` / `\"1y\"` / `\"2y\"`\n\n**labelType values (one per call):** `scenarios`, `issues`, `positives`, `improvements`, `buyingFactors`, `painPoints`, `keywords`, `userProfiles`, `usageTimes`, `usageLocations`, `behaviors`\n\n**Response:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `reviewCount` | int | Sample size |\n| `avgRating` | float | Overall satisfaction |\n| `sentimentDistribution` | object | Positive/neutral/negative ratio |\n| `consumerInsights` | list | Structured insights by dimension |\n| `topKeywords` | list | Trending terms |\n\n**InsightItem:** `{element, labelType, count, reviewRate, avgRating}`\n\n---\n\n## 7. products/price-band-overview\n\n**Request:** Same params as products/search (keyword, category, filters)\n\n**Response:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `sampleSkuCount` | int | Total products analyzed |\n| `sampleMedianPrice` | float | Median price point |\n| `hottestBand` | object | Highest sales share band |\n| `bestOpportunityBand` | object | Highest opportunity index band |\n\n**Band object:** `{bandIdx, bandLabel, sampleBandMinPrice, sampleBandMaxPrice, sampleSkuCount, sampleSalesRate, sampleBrandCount, sampleTop3BrandSalesRate, sampleAvgRating, sampleOpportunityIndex}`\n\n---\n\n## 8. products/price-band-detail\n\n**Response:**\n- `sampleSkuCount`, `sampleTotalMonthlySales`\n- `priceBands`: array of 5 band objects (same structure as above)\n\n---\n\n## 9. products/brand-overview\n\n**Response:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `sampleBrandCount` | int | Total brands |\n| `sampleTop10BrandSalesRate` | float | CR10 concentration (top 10 brands) |\n| `sampleTop10AvgRating` | float | Top 10 brand avg rating |\n| `sampleTop10AvgPrice` | float | Top 10 brand avg price |\n\n---\n\n## 10. products/brand-detail\n\n**Response:**\n- `sampleSkuCount`, `sampleTotalMonthlySales`, `sampleBrandCount`\n- `brands`: array of brand objects\n\n**BrandStats:** `{brandName, sampleSkuCount, sampleGroupMonthlySales, sampleGroupMonthlyRevenue, sampleSalesRate, sampleAvgPrice, minPrice, maxPrice, sampleAvgRating, sampleAvgRatingCount, sampleProducts}`\n\n**sampleProducts:** List of Product objects for this brand within the sample. Each product contains the full Shared Product Object fields (asin, title, price, bsr, monthlySalesFloor, rating, ratingCount, fulfillment, etc). This enables brand-level product matrix analysis without a separate products/search call.\n\n---\n\n## 11. products/history\n\n**Request:**\n- `asins`: List<String> (required)\n- `startDate`: String \"YYYY-MM-DD\" (required)\n- `endDate`: String \"YYYY-MM-DD\" (required)\n⚠️ Does NOT accept `dateRange` — must use startDate + endDate\n\n**Response (array of daily snapshots):**\n| Field | Type | Used For |\n|-------|------|----------|\n| `asin` | string | Product ID |\n| `price` | float | Price on that day |\n| `bsr` | int | BSR on that day |\n| `subBsr` | int | Sub-category BSR |\n| `recentSales` | int | Recent sales count |\n| `updatedAt` | string | Unix timestamp (string) |\n| `createdAt` | string | Unix timestamp (string) |\n\n---\n\n## Cross-Validation Matrix\n\n| Data Point | Primary Source | Validation Source |\n|-----------|---------------|-------------------|\n| Market size | markets/search | products/search (total count) |\n| Brand concentration | brand-overview (sampleTop10BrandSalesRate) | markets/search (topBrandSalesRate) |\n| Price distribution | price-band-detail | products/search (price field) |\n| Competition level | markets (topSalesRate) | brand-detail (top brand shares) |\n| Consumer demand | reviews/analysis | products (sales + growth) |\n| Avg rating quality | markets (sampleAvgRating) | brand-overview (sampleTop10AvgRating) |\n\nFile v1.1.8:skill-card.md\n\n## Description: <br>\nAmazon Competitor Intelligence Monitor helps agents run focused ZooData-powered competitor scans or monitoring checks for Amazon keywords, ASINs, brands, and defined competitor sets. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[apiclaw](https://clawhub.ai/user/apiclaw) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nExternal sellers, marketplace operators, and agent users use this skill to analyze known Amazon competitors, compare market position, identify pricing and review patterns, and monitor tracked ASINs for changes. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The runtime can resolve credentials from legacy APICLAW_API_KEY or ~/.apiclaw/config.json sources. <br>\nMitigation: Run the skill with a dedicated ZOODATA_API_KEY and do not expose unrelated legacy API keys or ~/.apiclaw/config.json to the agent environment. <br>\nRisk: Monitoring state and review fallback work files can leave competitor targets or review data in local directories. <br>\nMitigation: Periodically clean monitor-data and /tmp review work directories, especially in shared or long-lived agent runtimes. <br>\nRisk: Broad competitor scans can consume account credits quickly. <br>\nMitigation: Confirm estimated credit cost before multi-call scans and prefer granular commands when operating under a credit cap. <br>\n\n\n## Reference(s): <br>\n- [ClawHub skill page](https://clawhub.ai/apiclaw/skills/amazon-competitor-intelligence-monitor) <br>\n- [Project homepage](https://github.com/SerendipityOneInc/ZooData-Skills) <br>\n- [ZooData API keys](https://zoodata.ai/en/api-keys) <br>\n- [ZooData pricing](https://zoodata.ai/en/pricing) <br>\n- [ZooData API field reference](artifact/references/reference.md) <br>\n- [ZooData CLI contract](artifact/references/cli-contract.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance] <br>\n**Output Format:** [Markdown reports with tables, status messages, and optional shell commands; the bundled CLI produces JSON evidence for the agent to summarize.] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Reports should match the user's language, include confidence labels, data provenance, API usage, and credit consumption when API calls run.] <br>\n\n## Skill Version(s): <br>\n1.1.8 (source: skill metadata and server release evidence) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nArchive v1.1.7: 6 files, 45658 bytes\n\nFiles: README.md (3145b), references/reference.md (9267b), scripts/zoodata.py (153321b), skill-card.md (2857b), SKILL.md (14722b), _meta.json (157b)\n\nFile v1.1.7:SKILL.md\n\n---\nname: amazon-competitor-intelligence-monitor\ndescription: >\n  Amazon competitor intelligence engine. Produces analytical output focused on\n  a defined set of competitors: either a one-shot deep teardown (Full Scan:\n  28-35 credits, 11 endpoints, battle card, side-by-side comparison,\n  pricing/review/inventory breakdown) OR sustained per-competitor monitoring\n  with alerts (Quick Check: 5-10 credits, realtime polling, baseline diff).\n  Input: keyword, ASIN(s), or brand — whatever identifies the competitor set\n  to analyze. Output is per-competitor analytical insight tied to that\n  specific set.\n  Use when the user wants focused analysis on identified competitors:\n  a one-shot teardown or an ongoing per-competitor watch.\n  Use when user asks: analyze competitor B07XXX, battle card for ASIN Y,\n  side-by-side competitor teardown, spy on a brand, deep analysis of these\n  3 competitors, ongoing watch on a defined competitor set.\n  Requires ZOODATA_API_KEY.\nmetadata:\n  version: \"1.1.7\"\n  author: SerendipityOneInc\n  homepage: https://github.com/SerendipityOneInc/ZooData-Skills\n  openclaw: {\"requires\": {\"env\": [\"ZOODATA_API_KEY\"]}, \"primaryEnv\": \"ZOODATA_API_KEY\"}\n---\n\n# ZooData — Competitor Intelligence Monitor\n\n> Know your enemy. Two modes: Full Scan + Quick Check. Respond in user's language.\n\n## Files\n\n| File | Purpose |\n|------|---------|\n| `{skill_base_dir}/scripts/zoodata.py` | **Execute** for all API calls (run `--help` for params) |\n| `{skill_base_dir}/references/reference.md` | Load for exact field names or response structure |\n| `{skill_base_dir}/monitor-data/` | Runtime storage (auto-created): config.json, baseline.json, history/, alerts.json |\n\n## Credential\n\nRequired: `ZOODATA_API_KEY`. Get free key at [zoodata.ai/api-keys](https://zoodata.ai/en/api-keys).\n\n## Capabilities & Data Flow\n\n- **Network**: only `https://api.zoodata.ai` (Bearer `ZOODATA_API_KEY`). Setting `ZOODATA_BASE_URL` to an untrusted host (anything other than `api.zoodata.ai` / `*.zoodata.ai` / localhost) makes the CLI **refuse the request and withhold the key** — the Bearer token is never sent to an untrusted host.\n- **Execution**: bundled shared ZooData CLI `{skill_base_dir}/scripts/zoodata.py` (Python 3, stdlib-only). The shared CLI exposes ALL ZooData endpoints as subcommands; this skill's workflows use: `categories`, `market`, `competitors`, `products`, `product`, `history`, `analyze`, `competitor-analysis`, `check`, plus the review fallback toolkit (`reviews-raw` / `review-tag-prompt` / `review-reduce-prompt` / `review-aggregate`). Do not invoke unrelated subcommands for this skill's tasks.\n- **Local files**: a temporary `/tmp/review_<ASIN>_<timestamp>/` working dir during the review fallback; reads the optional credential store `~/.zoodata/config.json`.\n- **Sent to the API**: keywords, category paths, ASINs, marketplace/date and numeric filter values only. **Never sent**: budget, experience level, risk tolerance, or any other user-profile text — profile inputs map client-side to numeric filters.\n- **Credits**: every API call consumes account credits. For broad or ambiguous requests, state the estimated credit cost and confirm with the user before running multi-call scans. The composite `competitor-analysis` command executes ~17+ API calls (Full Scan, ~28-35 credits documented) in ONE invocation and has NO skip/trim flags — under a credit cap, use the granular commands instead.\n\n## Input\n\nRequired: keyword or ASIN(s). Optional: my_asin, competitor_asins, brand.\nIf only ASIN given → derive keyword via `product --asin` then ask user to confirm.\nBrand queries MUST also include confirmed `--category`.\n\n## API Pitfalls (CRITICAL)\n\n1. **Category auto-detection**: categoryPath is auto-detected from keyword, ASIN, or top search result. If `category_source` in output is `inferred_from_search`, MUST confirm with user before trusting results\n2. **All keyword-based endpoints MUST include `--category`**; ASIN-specific endpoints do NOT need it\n3. **Brand + category**: a brand sells across categories — only analyze within locked subcategory\n4. **Use API fields directly**: revenue=`sampleAvgMonthlyRevenue` (NEVER price×sales), sales=`monthlySalesFloor`, concentration=`sampleTop10BrandSalesRate`\n5. **reviews/analysis**: needs 50+ reviews. Fallback chain when sample is insufficient:\n   1. **Lightweight**: `realtime/product` ratingBreakdown — only star distribution, no themes\n   2. **Full 11-dim insights** — bypass `/reviews/analysis` entirely:\n      a. `zoodata.py reviews-raw --asin X` → fetch up to 100 raw reviews (10 credits, ~60s)\n      b. For each review: render Map prompt via `zoodata.py review-tag-prompt --review '<json>'`\n         and have your own LLM produce JSON tags (sentiment + 11 dimensions)\n      c. Collect candidate phrases per dimension; for each dimension render\n         Reduce prompt via `zoodata.py review-reduce-prompt --label-type X --candidates '[...]'`\n         and have your LLM produce semantic clusters\n      d. `zoodata.py review-aggregate --reviews R --tagged T --clusters C`\n         → consumerInsights output compatible with `/reviews/analysis`\n   3. **Fallback caveats** (apply to the 4-step chain above — lessons from end-to-end validation):\n      - **Working dir**: `WORK=/tmp/review_<ASIN>_$(date +%s) && mkdir -p $WORK`\n      - **Step b CLI behavior**: `review-tag-prompt` RENDERS the prompt only; YOUR LLM produces the JSON. Render once to learn the schema, then produce tags for all N reviews in one in-context pass (don't call the CLI N times).\n      - **Step c candidate extraction** (Python one-liner):\n        `candidates = {d: sorted({el.strip().lower() for t in tagged for el in (t.get(d) or [])}) for d in DIMS}`\n      - **Small-sample rule (reviewCount<50)**: demote single-mention items 📊→🔍; NEVER attach table-level or section-header 📊 when any row inside is 🔍; suppress \"🔴 Critical\" verdicts on count=1\n      - **Scope**: fallback replaces ONLY the `/reviews/analysis` aggregation. This skill's primary workflow outputs (competitor metrics, brand ranking, pricing, etc.) remain valid — do not re-run them.\n\n## On Missing Key\n\nWhen `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.\n## On 401 Invalid Key\n\nWhen `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.\n\n## On 402 Credit Exhausted\n\nWhen `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.\n\n## Mode Selection\n\n- **Full Scan** (~28-35 credits): First run, no baseline.json, explicit request, or weekly refresh\n- **Quick Check** (~5-10 credits): Cron trigger, baseline exists, \"check competitors\"\n\n## Full Scan Flow\n\n1. `competitor-analysis --keyword X [--category Y] [--my-asin Z]` (composite, auto-detects category)\n2. If `category_source` is `inferred_from_search`, confirm with user before presenting results\n3. Analyze & score → save baseline to `{skill_base_dir}/monitor-data/` → offer Auto-Monitor\n\n## Quick Check Flow\n\n1. Load config.json + baseline.json from `{skill_base_dir}/monitor-data/` (missing → fall back to Full Scan)\n2. Poll `product --asin {asin}` for each tracked ASIN\n3. Diff against baseline with tiered alerts → update baseline → offer Auto-Monitor\n\n## Alert Tiers\n\n| 🔴 Critical | 🟡 Watch | 🟢 Opportunity |\n|-------------|----------|----------------|\n| Price change > threshold | FBA↔FBM switch | Competitor stock-out |\n| BSR crash > threshold | Rating change | Bullet/image changes |\n| Buy Box owner changed | Abnormal review growth | Variant added/removed |\n| | Title modified | |\n\n## Competitive Score (per competitor, 1-100)\n\n| Dimension | Weight | 80-100 (Strong) | 50-79 (Moderate) | 0-49 (Weak) |\n|-----------|--------|-----------------|-------------------|-------------|\n| Sales Dominance | 25% | Top 3 in category, >5K units/mo 📊 | Top 20, 1K-5K units/mo 📊 | Below Top 20, <1K units/mo 📊 |\n| Brand Strength | 20% | Brand in CR10, 5+ SKUs, wide price range 📊 | Known brand, 2-4 SKUs 📊 | Unknown brand, single SKU 📊 |\n| Listing Quality | 20% | 7+ images, 5 bullets, A+, optimized title 📊 | 5-6 images, basic bullets 📊 | <5 images, weak bullets, no A+ 📊 |\n| Customer Satisfaction | 20% | Rating ≥4.5, <3% 1-star, positive sentiment 📊 | 4.0-4.4, 3-8% 1-star 📊 | <4.0 or >8% 1-star 📊 |\n| Trend Momentum | 15% | BSR improving 30d, sales growth >10% 🔍 | BSR stable, flat sales 🔍 | BSR declining, sales drop 🔍 |\n\n### Competitive Threat Level\n| Total Score | Threat | Interpretation |\n|-------------|--------|---------------|\n| 80-100 | 🔴 Dominant | Hard to compete head-on; find differentiation or avoid price band 💡 |\n| 50-79 | 🟡 Competitive | Beatable with better listing, pricing, or reviews 💡 |\n| 0-49 | 🟢 Vulnerable | Weak competitor; opportunity to capture share 💡 |\n\n### Market Structure Analysis\n- **CR10 > 70%**: Concentrated market — new entrants need strong differentiation or niche positioning 🔍\n- **CR10 40-70%**: Moderately competitive — room for well-positioned products 🔍\n- **CR10 < 40%**: Fragmented — opportunity for brand building 🔍\n- **Top brand share > 25%**: Category leader dominance — avoid direct competition in their price band 💡\n- **New SKU rate > 15%**: Active market with frequent new entrants 📊\n- **New SKU rate < 5%**: Mature/stagnant market, high barriers 🔍\n\n## Auto-Monitor Prompt\n\nAfter EVERY run, offer: \"Set up automatic monitoring? I can generate a scheduled Quick Check.\" Provide platform-specific setup (OpenClaw `/cron`, ChatGPT Scheduled Tasks, Claude Projects).\n\n## Output Spec\n\nFull Scan sections: Battlefield Overview → Competitor Matrix → Brand Power Ranking → Price Map → 30-Day Trends → Review Battle → Listing Audit → Competitive Scores → Battle Strategy → Data Provenance → API Usage.\n\n### Language (required)\n\nOutput 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.\n\n### Disclaimer (required, at the top of every report)\n\n> 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.\n\n### Confidence Labels (required, tag EVERY conclusion)\n\n- 📊 **Data-backed** — direct API data (e.g. \"CR10 = 54.8% 📊\")\n- 🔍 **Inferred** — logical reasoning from data (e.g. \"brand concentration is moderate 🔍\")\n- 💡 **Directional** — suggestions, predictions, strategy (e.g. \"consider entering $10-15 band 💡\")\n\nRules: Strategy recommendations are NEVER 📊. Anomalies (>200% growth) are always 💡. User criteria override AI judgment.\n\n**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:\n- Section headers at EVERY level (`#`, `##`, `###`, `####`) — including top-level summary sections like \"Overall Score\", \"Verdict\", \"Executive Summary\"\n- Summary/score lines anywhere in the report (e.g. `## Overall Score — 27/100 · Grade F 📊` is WRONG if any Basis row inside is 🔍)\n- Table **column** headers in comparison tables (e.g. `**Target ASIN** 📊` as a column label is WRONG if any cell in that column contains 🔍)\n- Table row headers or row-aggregation labels (when the row aggregates multiple cells of mixed confidence)\n- Any other visual grouping label — bullet-list group titles, callout box titles, etc.\n\nA 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.\n\n**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:\n- ❌ WRONG: `## 📊 Overall Score — 27/100 · Grade F 🔍` (the leading 📊 reads as a data-backed claim even though the trailing 🔍 is correct)\n- ✅ RIGHT: `## Overall Score — 27/100 · Grade F 🔍` (no decorative emoji, just the proper confidence suffix)\n- ✅ RIGHT: `## 🎯 Overall Score — 27/100 · Grade F 🔍` (use non-reserved decorative icons like 🎯 🧭 📋 📝 📂 🏁 🚨 🏆 🔔 when a visual prefix is desired)\n\nDecorative 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.\n\n### Data Provenance (required)\n\nInclude a table at the end of every report:\n\n| Data | Endpoint | Key Params | Notes |\n|------|----------|------------|-------|\n| (e.g. Market Overview) | `markets/search` | categoryPath, topN=10 | 📊 Top N sampling, sales are lower-bound |\n| ... | ... | ... | ... |\n\nExtract endpoint and params from `_query` in JSON output. Add notes: sampling method, T+1 delay, realtime vs DB, minimum review threshold, etc.\n\n### API Usage (required)\n\n| Endpoint | Calls | Credits |\n|----------|-------|---------|\n| (each endpoint used) | N | N |\n| **Total** | **N** | **N** |\n\nExtract from `meta.creditsConsumed` per response. End with `Credits remaining: N`.\n\n## API Budget\n\nFull Scan: ~28-35 credits (all 11 endpoints via composite). Quick Check: ~5-10 credits (realtime/product × N ASINs).\n\nFile v1.1.7:README.md\n\n# Amazon Competitor Intelligence Monitor — ZooData Agent Skill\n\n> Know your enemy. Full Scan + Quick Check. Always watching.\n\n## What This Skill Does\n\nDeep competitor intelligence with two operational modes. **Full Scan** delivers a complete competitive landscape — competitor matrix, brand ranking, pricing map, review battle, and battle strategy. **Quick Check** polls tracked ASINs against a saved baseline and fires tiered alerts when something changes.\n\n### What Makes This Different\n\n- **Dual-mode**: Full Scan (~28-35 credits) for deep analysis, Quick Check (~5-10 credits) for lightweight monitoring\n- **Three-tier alerts**: 🔴 Critical (price crash, Buy Box lost), 🟡 Watch (FBA switch, rating shift), 🟢 Opportunity (stock-out, listing changes)\n- **Competitive Score**: Each competitor scored 1-100 across 5 dimensions (sales, brand, listing, satisfaction, trend)\n- **Auto-Monitor**: Offers scheduled Quick Check setup after every run\n\n## Install\n\n```bash\nnpx skills add SerendipityOneInc/ZooData-Skills\n```\n\nSelect **Amazon Competitor Intelligence Monitor** when prompted.\n\n## API Key Setup\n\n1. Get a free key at [zoodata.ai/api-keys](https://zoodata.ai/en/api-keys) — 1,000 free credits, no credit card\n2. Set the environment variable:\n   ```bash\n   export ZOODATA_API_KEY='hms_live_xxxxxx'\n   ```\n\n## Example Prompts\n\n- *\"Analyze my competitors for ASIN B0XXXXXXXX in the yoga mat market\"*\n- *\"Run a full competitor scan for keyword 'silicone spatula'\"*\n- *\"Quick check my tracked competitors\"*\n- *\"Who are the top competitors for 'dog harness' and how do I beat them?\"*\n- *\"Monitor competitor price changes and alert me on anomalies\"*\n\n## What You Get\n\n| Section | Description |\n|---------|-------------|\n| ⚔️ Battlefield Overview | Market size, player count, concentration |\n| 📊 Competitor Matrix | Side-by-side comparison of all key competitors |\n| 🏅 Brand Power Ranking | Brand strength scores and market share |\n| 💰 Price Map | Price positioning across competitors |\n| 📈 30-Day Trends | BSR, price, and sales movement |\n| 💬 Review Battle | Rating, sentiment, pain points per competitor |\n| 📋 Listing Audit | Image, bullet, A+ content comparison |\n| 🎯 Battle Strategy | Actionable recommendations to outperform |\n| 🚨 Alerts (Quick Check) | Tiered change detection vs baseline |\n\n## API Endpoints Used\n\n| Endpoint | Purpose |\n|----------|---------|\n| `categories` | Category resolution |\n| `markets/search` | Market context |\n| `products/search` | Product landscape |\n| `products/competitors` | Competitor discovery |\n| `realtime/product` | Live competitor data |\n| `reviews/analysis` | Sentiment & pain points |\n| `products/price-band-overview` | Price band context |\n| `products/price-band-detail` | Detailed price analysis |\n| `products/brand-overview` | Brand concentration |\n| `products/brand-detail` | Per-brand breakdown |\n| `products/history` | Trend analysis |\n\n## Credit Cost\n\nFull Scan: ~28-35 credits. Quick Check: ~5-10 credits.\n\n## Powered By\n\n[ZooData](https://zoodata.ai) — The data infrastructure built for agents. 200M+ Amazon products, 1B+ reviews, real-time signals.\n\nFile v1.1.7:_meta.json\n\n{\n  \"ownerId\": \"kn78k155f6rbh2j8r8yjx8r2e18304q9\",\n  \"slug\": \"amazon-competitor-intelligence-monitor\",\n  \"version\": \"1.1.7\",\n  \"publishedAt\": 1785314122472\n}\n\nFile v1.1.7:references/reference.md\n\n# ZooData API Field Reference\n\n> Load this file only when you need exact field names or response structure.\n\n## ZooData Endpoint Field Reference\n\n> Shared field reference. This skill's workflows use ONLY the subcommands\n> listed in its SKILL.md; the endpoints below are documented for field-name /\n> response-structure lookup, not as a claim that this skill invokes all of them.\n\n| # | Endpoint | Purpose |\n|---|----------|---------|\n| 1 | `categories` | Category path lookup |\n| 2 | `markets/search` | Market size, competition metrics, new-product rate |\n| 3 | `products/search` | Product supply (100+ via pagination), brand/price drill |\n| 4 | `products/competitors` | Top competitor list |\n| 5 | `realtime/product` | Live product detail |\n| 6 | `reviews/analysis` | Consumer pain points, buying factors |\n| 7 | `products/price-band-overview` | Price-band opportunity overview |\n| 8 | `products/price-band-detail` | Per-band SKU/sales/brand/rating breakdown |\n| 9 | `products/brand-overview` | Brand count, CR10, top-brand avg price/rating |\n| 10 | `products/brand-detail` | Per-brand SKU/sales/revenue/share ranking |\n| 11 | `products/history` | 30-day price/BSR/sales trend |\n\nBase URL: `https://api.zoodata.ai/openapi/v2`\nAuth: `Bearer $ZOODATA_API_KEY`\nMethod: All POST with JSON body\nAll endpoints return: `{success, data, error, meta}` with `meta.creditsRemaining`\n\n---\n\n## 1. categories\n\n**Request:** (mutually exclusive modes)\n- No params → root categories\n- `categoryKeyword`: String → search by keyword\n- `categoryPath`: List<String> → exact path\n- `parentCategoryPath`: List<String> → child categories\n\n**Response:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `categoryId` | string | Category ID |\n| `categoryName` | string | Category name |\n| `categoryPath` | list | Full path from root |\n| `hasChildren` | bool | Has subcategories |\n| `level` | int | Depth (1=root) |\n| `productCount` | int | Products in category |\n\n---\n\n## 2. markets/search\n\n**Key Request Params:**\n- `categoryPath`: List<String> (e.g. `[\"Pet Supplies\", \"Dogs\"]`)\n- `categoryKeyword`: String\n- `topN`: **String** (`\"10\"` not `10`)\n- `sampleType`: `by_sale_100` / `by_bsr_100` / `avg`\n- `pageSize`: Integer (max 20)\n\n**Key Response Fields:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `totalSkuCount` | int | Market size |\n| `sampleAvgMonthlySales` | float | Demand level |\n| `sampleAvgMonthlyRevenue` | float | Market value |\n| `sampleAvgPrice` | float | Price benchmark |\n| `sampleAvgRating` | float | Quality benchmark |\n| `sampleBrandCount` | int | Brand diversity |\n| `sampleSellerCount` | int | Seller diversity |\n| `sampleFbaRate` | float | FBA adoption (decimal) |\n| `sampleNewSkuRate` | float | New entrant rate (decimal) |\n| `topSalesRate` | float | Product concentration (CR_topN) |\n| `topBrandSalesRate` | float | Brand concentration |\n| `topSellerSalesRate` | float | Seller concentration |\n| `sampleAPlusRate` | float | Margin benchmark |\n\n---\n\n## 3. products/search — Shared Product Object\n\n**Key Request Params:**\n- `keyword`, `categoryPath`, `keywordMatchType` (`mode` is a CLI-only preset — `zoodata.py` expands it into the filter pairs below client-side; it is NOT an API field and returns 422 if sent raw)\n- Filter pairs: `monthlySalesMin/Max`, `priceMin/Max`, `ratingMin/Max`, etc.\n- `pageSize` (max 20), `page`, `sortBy`, `sortOrder`\n- `includeBrands`, `excludeBrands`\n\n**Key Response Fields (per product):**\n| Field | Type | Used For |\n|-------|------|----------|\n| `asin` | string | Product ID |\n| `title` | string | Product name |\n| `brandName` | string | Brand |\n| `price` | float | Price |\n| `monthlySalesFloor` | int | Monthly sales (lower bound) |\n| `monthlyRevenueFloor` | float | Monthly revenue lower bound |\n| `rating` | float | Rating (0-5) |\n| `ratingCount` | int | Review count |\n| `bsr` | int | BSR (NOT `bestsellersRank`) |\n| `fbaFee` | float | FBA cost |\n| `sellerCount` | int | Sellers on listing |\n| `fulfillment` | string | FBA/FBM/AMZ |\n| `listingDate` | string | When listed |\n| `salesGrowthRate` | float | Growth rate |\n| `variantCount` | int | Variants |\n\n---\n\n## 4. products/competitors\n\nSame response as products/search. Different use: discovery by keyword/brand/asin.\nRequest params: `keyword`, `brand`, `asin`, `categoryPath`, `sortBy`, `pageSize`\n\n---\n\n## 5. realtime/product\n\n**Request:**\n- `asin`: String (required)\n- `marketplace`: String (US/UK/DE/FR/IT/ES/JP/CA/AU/IN/MX/BR, default US)\n\n**Response:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `asin` | string | Product ID |\n| `title` | string | Full title |\n| `brandName` | string | Brand |\n| `rating` | float | Current rating |\n| `ratingCount` | int | Current review count |\n| `ratingBreakdown` | object | Star distribution {five_star: {percentage, count}, ...} |\n| `features` | list | Bullet points |\n| `description` | string | Product description |\n| `specifications` | object | Tech specs |\n| `variants` | list | All variants with dimensions |\n| `bestsellersRank` | list | BSR info [{category, rank}, ...] |\n| `buyboxWinner` | object | Buy Box: {price, fulfillment, seller} |\n| `images` | list | All image URLs |\n\n⚠️ Does NOT have: monthlySalesFloor, fbaFee, sellerCount\n\n---\n\n## 6. reviews/analysis\n\n**Request:**\n- `mode`: `\"asin\"` or `\"category\"`\n- `asins`: List<String> (when mode=asin)\n- `categoryPath`: String (when mode=category)\n- `labelType`: filter to specific dimensions. **⚠️ Only ONE value per call — do NOT comma-separate multiple types.** Make separate calls for each labelType needed.\n- `period`: e.g. `\"1m\"` / `\"3m\"` / `\"6m\"` / `\"1y\"` / `\"2y\"`\n\n**labelType values (one per call):** `scenarios`, `issues`, `positives`, `improvements`, `buyingFactors`, `painPoints`, `keywords`, `userProfiles`, `usageTimes`, `usageLocations`, `behaviors`\n\n**Response:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `reviewCount` | int | Sample size |\n| `avgRating` | float | Overall satisfaction |\n| `sentimentDistribution` | object | Positive/neutral/negative ratio |\n| `consumerInsights` | list | Structured insights by dimension |\n| `topKeywords` | list | Trending terms |\n\n**InsightItem:** `{element, labelType, count, reviewRate, avgRating}`\n\n---\n\n## 7. products/price-band-overview\n\n**Request:** Same params as products/search (keyword, category, filters)\n\n**Response:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `sampleSkuCount` | int | Total products analyzed |\n| `sampleMedianPrice` | float | Median price point |\n| `hottestBand` | object | Highest sales share band |\n| `bestOpportunityBand` | object | Highest opportunity index band |\n\n**Band object:** `{bandIdx, bandLabel, sampleBandMinPrice, sampleBandMaxPrice, sampleSkuCount, sampleSalesRate, sampleBrandCount, sampleTop3BrandSalesRate, sampleAvgRating, sampleOpportunityIndex}`\n\n---\n\n## 8. products/price-band-detail\n\n**Response:**\n- `sampleSkuCount`, `sampleTotalMonthlySales`\n- `priceBands`: array of 5 band objects (same structure as above)\n\n---\n\n## 9. products/brand-overview\n\n**Response:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `sampleBrandCount` | int | Total brands |\n| `sampleTop10BrandSalesRate` | float | CR10 concentration (top 10 brands) |\n| `sampleTop10AvgRating` | float | Top 10 brand avg rating |\n| `sampleTop10AvgPrice` | float | Top 10 brand avg price |\n\n---\n\n## 10. products/brand-detail\n\n**Response:**\n- `sampleSkuCount`, `sampleTotalMonthlySales`, `sampleBrandCount`\n- `brands`: array of brand objects\n\n**BrandStats:** `{brandName, sampleSkuCount, sampleGroupMonthlySales, sampleGroupMonthlyRevenue, sampleSalesRate, sampleAvgPrice, minPrice, maxPrice, sampleAvgRating, sampleAvgRatingCount, sampleProducts}`\n\n**sampleProducts:** List of Product objects for this brand within the sample. Each product contains the full Shared Product Object fields (asin, title, price, bsr, monthlySalesFloor, rating, ratingCount, fulfillment, etc). This enables brand-level product matrix analysis without a separate products/search call.\n\n---\n\n## 11. products/history\n\n**Request:**\n- `asins`: List<String> (required)\n- `startDate`: String \"YYYY-MM-DD\" (required)\n- `endDate`: String \"YYYY-MM-DD\" (required)\n⚠️ Does NOT accept `dateRange` — must use startDate + endDate\n\n**Response (array of daily snapshots):**\n| Field | Type | Used For |\n|-------|------|----------|\n| `asin` | string | Product ID |\n| `price` | float | Price on that day |\n| `bsr` | int | BSR on that day |\n| `subBsr` | int | Sub-category BSR |\n| `recentSales` | int | Recent sales count |\n| `updatedAt` | string | Unix timestamp (string) |\n| `createdAt` | string | Unix timestamp (string) |\n\n---\n\n## Cross-Validation Matrix\n\n| Data Point | Primary Source | Validation Source |\n|-----------|---------------|-------------------|\n| Market size | markets/search | products/search (total count) |\n| Brand concentration | brand-overview (sampleTop10BrandSalesRate) | markets/search (topBrandSalesRate) |\n| Price distribution | price-band-detail | products/search (price field) |\n| Competition level | markets (topSalesRate) | brand-detail (top brand shares) |\n| Consumer demand | reviews/analysis | products (sales + growth) |\n| Avg rating quality | markets (sampleAvgRating) | brand-overview (sampleTop10AvgRating) |\n\nFile v1.1.7:skill-card.md\n\n## Description: <br>\nAmazon competitor intelligence engine that produces focused one-shot competitor teardowns or sustained per-competitor monitoring with alerts from a keyword, ASIN, or brand input. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[apiclaw](https://clawhub.ai/user/apiclaw) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nExternal sellers, operators, and market analysts use this skill to analyze defined Amazon competitor sets, compare market position, and monitor tracked ASINs for pricing, listing, review, inventory, and trend changes. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The skill requires a ZooData API key and can spend ZooData credits during competitor scans. <br>\nMitigation: Install only when API-key use and credit spending are acceptable; confirm estimated costs before broad or multi-call scans. <br>\nRisk: Monitoring and review fallback workflows can retain local baselines, alerts, history, and temporary review-processing files. <br>\nMitigation: Review or delete the skill's monitor-data directory and any /tmp/review_* folders when retained local files are not desired. <br>\nRisk: Competitor analysis is based on sampled ZooData API responses and may include lower-bound estimates or inferred recommendations. <br>\nMitigation: Keep the report disclaimer and confidence labels visible, and validate important business decisions with additional sources before acting. <br>\n\n\n## Reference(s): <br>\n- [ClawHub skill page](https://clawhub.ai/apiclaw/skills/amazon-competitor-intelligence-monitor) <br>\n- [Publisher profile](https://clawhub.ai/user/apiclaw) <br>\n- [Project homepage](https://github.com/SerendipityOneInc/ZooData-Skills) <br>\n- [ZooData API field reference](references/reference.md) <br>\n- [ZooData API documentation](https://api.zoodata.ai/api-docs) <br>\n- [ZooData API key setup](https://zoodata.ai/en/api-keys) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance] <br>\n**Output Format:** [Markdown reports with tables, inline shell commands, confidence labels, data provenance, and API usage summaries.] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Outputs should match the user's language and may persist monitoring baselines, history, alerts, and review-processing work files when monitoring or fallback review workflows are used.] <br>\n\n## Skill Version(s): <br>\n1.1.7 (source: release evidence and skill metadata) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nArchive v1.1.6: 6 files, 45643 bytes\n\nFiles: README.md (3145b), references/reference.md (9262b), scripts/zoodata.py (153321b), skill-card.md (2793b), SKILL.md (14722b), _meta.json (157b)\n\nFile v1.1.6:SKILL.md\n\n---\nname: amazon-competitor-intelligence-monitor\ndescription: >\n  Amazon competitor intelligence engine. Produces analytical output focused on\n  a defined set of competitors: either a one-shot deep teardown (Full Scan:\n  28-35 credits, 11 endpoints, battle card, side-by-side comparison,\n  pricing/review/inventory breakdown) OR sustained per-competitor monitoring\n  with alerts (Quick Check: 5-10 credits, realtime polling, baseline diff).\n  Input: keyword, ASIN(s), or brand — whatever identifies the competitor set\n  to analyze. Output is per-competitor analytical insight tied to that\n  specific set.\n  Use when the user wants focused analysis on identified competitors:\n  a one-shot teardown or an ongoing per-competitor watch.\n  Use when user asks: analyze competitor B07XXX, battle card for ASIN Y,\n  side-by-side competitor teardown, spy on a brand, deep analysis of these\n  3 competitors, ongoing watch on a defined competitor set.\n  Requires ZOODATA_API_KEY.\nmetadata:\n  version: \"1.1.6\"\n  author: SerendipityOneInc\n  homepage: https://github.com/SerendipityOneInc/ZooData-Skills\n  openclaw: {\"requires\": {\"env\": [\"ZOODATA_API_KEY\"]}, \"primaryEnv\": \"ZOODATA_API_KEY\"}\n---\n\n# ZooData — Competitor Intelligence Monitor\n\n> Know your enemy. Two modes: Full Scan + Quick Check. Respond in user's language.\n\n## Files\n\n| File | Purpose |\n|------|---------|\n| `{skill_base_dir}/scripts/zoodata.py` | **Execute** for all API calls (run `--help` for params) |\n| `{skill_base_dir}/references/reference.md` | Load for exact field names or response structure |\n| `{skill_base_dir}/monitor-data/` | Runtime storage (auto-created): config.json, baseline.json, history/, alerts.json |\n\n## Credential\n\nRequired: `ZOODATA_API_KEY`. Get free key at [zoodata.ai/api-keys](https://zoodata.ai/en/api-keys).\n\n## Capabilities & Data Flow\n\n- **Network**: only `https://api.zoodata.ai` (Bearer `ZOODATA_API_KEY`). Setting `ZOODATA_BASE_URL` to an untrusted host (anything other than `api.zoodata.ai` / `*.zoodata.ai` / localhost) makes the CLI **refuse the request and withhold the key** — the Bearer token is never sent to an untrusted host.\n- **Execution**: bundled shared ZooData CLI `{skill_base_dir}/scripts/zoodata.py` (Python 3, stdlib-only). The shared CLI exposes ALL ZooData endpoints as subcommands; this skill's workflows use: `categories`, `market`, `competitors`, `products`, `product`, `history`, `analyze`, `competitor-analysis`, `check`, plus the review fallback toolkit (`reviews-raw` / `review-tag-prompt` / `review-reduce-prompt` / `review-aggregate`). Do not invoke unrelated subcommands for this skill's tasks.\n- **Local files**: a temporary `/tmp/review_<ASIN>_<timestamp>/` working dir during the review fallback; reads the optional credential store `~/.zoodata/config.json`.\n- **Sent to the API**: keywords, category paths, ASINs, marketplace/date and numeric filter values only. **Never sent**: budget, experience level, risk tolerance, or any other user-profile text — profile inputs map client-side to numeric filters.\n- **Credits**: every API call consumes account credits. For broad or ambiguous requests, state the estimated credit cost and confirm with the user before running multi-call scans. The composite `competitor-analysis` command executes ~17+ API calls (Full Scan, ~28-35 credits documented) in ONE invocation and has NO skip/trim flags — under a credit cap, use the granular commands instead.\n\n## Input\n\nRequired: keyword or ASIN(s). Optional: my_asin, competitor_asins, brand.\nIf only ASIN given → derive keyword via `product --asin` then ask user to confirm.\nBrand queries MUST also include confirmed `--category`.\n\n## API Pitfalls (CRITICAL)\n\n1. **Category auto-detection**: categoryPath is auto-detected from keyword, ASIN, or top search result. If `category_source` in output is `inferred_from_search`, MUST confirm with user before trusting results\n2. **All keyword-based endpoints MUST include `--category`**; ASIN-specific endpoints do NOT need it\n3. **Brand + category**: a brand sells across categories — only analyze within locked subcategory\n4. **Use API fields directly**: revenue=`sampleAvgMonthlyRevenue` (NEVER price×sales), sales=`monthlySalesFloor`, concentration=`sampleTop10BrandSalesRate`\n5. **reviews/analysis**: needs 50+ reviews. Fallback chain when sample is insufficient:\n   1. **Lightweight**: `realtime/product` ratingBreakdown — only star distribution, no themes\n   2. **Full 11-dim insights** — bypass `/reviews/analysis` entirely:\n      a. `zoodata.py reviews-raw --asin X` → fetch up to 100 raw reviews (10 credits, ~60s)\n      b. For each review: render Map prompt via `zoodata.py review-tag-prompt --review '<json>'`\n         and have your own LLM produce JSON tags (sentiment + 11 dimensions)\n      c. Collect candidate phrases per dimension; for each dimension render\n         Reduce prompt via `zoodata.py review-reduce-prompt --label-type X --candidates '[...]'`\n         and have your LLM produce semantic clusters\n      d. `zoodata.py review-aggregate --reviews R --tagged T --clusters C`\n         → consumerInsights output compatible with `/reviews/analysis`\n   3. **Fallback caveats** (apply to the 4-step chain above — lessons from end-to-end validation):\n      - **Working dir**: `WORK=/tmp/review_<ASIN>_$(date +%s) && mkdir -p $WORK`\n      - **Step b CLI behavior**: `review-tag-prompt` RENDERS the prompt only; YOUR LLM produces the JSON. Render once to learn the schema, then produce tags for all N reviews in one in-context pass (don't call the CLI N times).\n      - **Step c candidate extraction** (Python one-liner):\n        `candidates = {d: sorted({el.strip().lower() for t in tagged for el in (t.get(d) or [])}) for d in DIMS}`\n      - **Small-sample rule (reviewCount<50)**: demote single-mention items 📊→🔍; NEVER attach table-level or section-header 📊 when any row inside is 🔍; suppress \"🔴 Critical\" verdicts on count=1\n      - **Scope**: fallback replaces ONLY the `/reviews/analysis` aggregation. This skill's primary workflow outputs (competitor metrics, brand ranking, pricing, etc.) remain valid — do not re-run them.\n\n## On Missing Key\n\nWhen `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.\n## On 401 Invalid Key\n\nWhen `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.\n\n## On 402 Credit Exhausted\n\nWhen `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.\n\n## Mode Selection\n\n- **Full Scan** (~28-35 credits): First run, no baseline.json, explicit request, or weekly refresh\n- **Quick Check** (~5-10 credits): Cron trigger, baseline exists, \"check competitors\"\n\n## Full Scan Flow\n\n1. `competitor-analysis --keyword X [--category Y] [--my-asin Z]` (composite, auto-detects category)\n2. If `category_source` is `inferred_from_search`, confirm with user before presenting results\n3. Analyze & score → save baseline to `{skill_base_dir}/monitor-data/` → offer Auto-Monitor\n\n## Quick Check Flow\n\n1. Load config.json + baseline.json from `{skill_base_dir}/monitor-data/` (missing → fall back to Full Scan)\n2. Poll `product --asin {asin}` for each tracked ASIN\n3. Diff against baseline with tiered alerts → update baseline → offer Auto-Monitor\n\n## Alert Tiers\n\n| 🔴 Critical | 🟡 Watch | 🟢 Opportunity |\n|-------------|----------|----------------|\n| Price change > threshold | FBA↔FBM switch | Competitor stock-out |\n| BSR crash > threshold | Rating change | Bullet/image changes |\n| Buy Box owner changed | Abnormal review growth | Variant added/removed |\n| | Title modified | |\n\n## Competitive Score (per competitor, 1-100)\n\n| Dimension | Weight | 80-100 (Strong) | 50-79 (Moderate) | 0-49 (Weak) |\n|-----------|--------|-----------------|-------------------|-------------|\n| Sales Dominance | 25% | Top 3 in category, >5K units/mo 📊 | Top 20, 1K-5K units/mo 📊 | Below Top 20, <1K units/mo 📊 |\n| Brand Strength | 20% | Brand in CR10, 5+ SKUs, wide price range 📊 | Known brand, 2-4 SKUs 📊 | Unknown brand, single SKU 📊 |\n| Listing Quality | 20% | 7+ images, 5 bullets, A+, optimized title 📊 | 5-6 images, basic bullets 📊 | <5 images, weak bullets, no A+ 📊 |\n| Customer Satisfaction | 20% | Rating ≥4.5, <3% 1-star, positive sentiment 📊 | 4.0-4.4, 3-8% 1-star 📊 | <4.0 or >8% 1-star 📊 |\n| Trend Momentum | 15% | BSR improving 30d, sales growth >10% 🔍 | BSR stable, flat sales 🔍 | BSR declining, sales drop 🔍 |\n\n### Competitive Threat Level\n| Total Score | Threat | Interpretation |\n|-------------|--------|---------------|\n| 80-100 | 🔴 Dominant | Hard to compete head-on; find differentiation or avoid price band 💡 |\n| 50-79 | 🟡 Competitive | Beatable with better listing, pricing, or reviews 💡 |\n| 0-49 | 🟢 Vulnerable | Weak competitor; opportunity to capture share 💡 |\n\n### Market Structure Analysis\n- **CR10 > 70%**: Concentrated market — new entrants need strong differentiation or niche positioning 🔍\n- **CR10 40-70%**: Moderately competitive — room for well-positioned products 🔍\n- **CR10 < 40%**: Fragmented — opportunity for brand building 🔍\n- **Top brand share > 25%**: Category leader dominance — avoid direct competition in their price band 💡\n- **New SKU rate > 15%**: Active market with frequent new entrants 📊\n- **New SKU rate < 5%**: Mature/stagnant market, high barriers 🔍\n\n## Auto-Monitor Prompt\n\nAfter EVERY run, offer: \"Set up automatic monitoring? I can generate a scheduled Quick Check.\" Provide platform-specific setup (OpenClaw `/cron`, ChatGPT Scheduled Tasks, Claude Projects).\n\n## Output Spec\n\nFull Scan sections: Battlefield Overview → Competitor Matrix → Brand Power Ranking → Price Map → 30-Day Trends → Review Battle → Listing Audit → Competitive Scores → Battle Strategy → Data Provenance → API Usage.\n\n### Language (required)\n\nOutput 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.\n\n### Disclaimer (required, at the top of every report)\n\n> 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.\n\n### Confidence Labels (required, tag EVERY conclusion)\n\n- 📊 **Data-backed** — direct API data (e.g. \"CR10 = 54.8% 📊\")\n- 🔍 **Inferred** — logical reasoning from data (e.g. \"brand concentration is moderate 🔍\")\n- 💡 **Directional** — suggestions, predictions, strategy (e.g. \"consider entering $10-15 band 💡\")\n\nRules: Strategy recommendations are NEVER 📊. Anomalies (>200% growth) are always 💡. User criteria override AI judgment.\n\n**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:\n- Section headers at EVERY level (`#`, `##`, `###`, `####`) — including top-level summary sections like \"Overall Score\", \"Verdict\", \"Executive Summary\"\n- Summary/score lines anywhere in the report (e.g. `## Overall Score — 27/100 · Grade F 📊` is WRONG if any Basis row inside is 🔍)\n- Table **column** headers in comparison tables (e.g. `**Target ASIN** 📊` as a column label is WRONG if any cell in that column contains 🔍)\n- Table row headers or row-aggregation labels (when the row aggregates multiple cells of mixed confidence)\n- Any other visual grouping label — bullet-list group titles, callout box titles, etc.\n\nA 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.\n\n**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:\n- ❌ WRONG: `## 📊 Overall Score — 27/100 · Grade F 🔍` (the leading 📊 reads as a data-backed claim even though the trailing 🔍 is correct)\n- ✅ RIGHT: `## Overall Score — 27/100 · Grade F 🔍` (no decorative emoji, just the proper confidence suffix)\n- ✅ RIGHT: `## 🎯 Overall Score — 27/100 · Grade F 🔍` (use non-reserved decorative icons like 🎯 🧭 📋 📝 📂 🏁 🚨 🏆 🔔 when a visual prefix is desired)\n\nDecorative 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.\n\n### Data Provenance (required)\n\nInclude a table at the end of every report:\n\n| Data | Endpoint | Key Params | Notes |\n|------|----------|------------|-------|\n| (e.g. Market Overview) | `markets/search` | categoryPath, topN=10 | 📊 Top N sampling, sales are lower-bound |\n| ... | ... | ... | ... |\n\nExtract endpoint and params from `_query` in JSON output. Add notes: sampling method, T+1 delay, realtime vs DB, minimum review threshold, etc.\n\n### API Usage (required)\n\n| Endpoint | Calls | Credits |\n|----------|-------|---------|\n| (each endpoint used) | N | N |\n| **Total** | **N** | **N** |\n\nExtract from `meta.creditsConsumed` per response. End with `Credits remaining: N`.\n\n## API Budget\n\nFull Scan: ~28-35 credits (all 11 endpoints via composite). Quick Check: ~5-10 credits (realtime/product × N ASINs).\n\nFile v1.1.6:README.md\n\n# Amazon Competitor Intelligence Monitor — ZooData Agent Skill\n\n> Know your enemy. Full Scan + Quick Check. Always watching.\n\n## What This Skill Does\n\nDeep competitor intelligence with two operational modes. **Full Scan** delivers a complete competitive landscape — competitor matrix, brand ranking, pricing map, review battle, and battle strategy. **Quick Check** polls tracked ASINs against a saved baseline and fires tiered alerts when something changes.\n\n### What Makes This Different\n\n- **Dual-mode**: Full Scan (~28-35 credits) for deep analysis, Quick Check (~5-10 credits) for lightweight monitoring\n- **Three-tier alerts**: 🔴 Critical (price crash, Buy Box lost), 🟡 Watch (FBA switch, rating shift), 🟢 Opportunity (stock-out, listing changes)\n- **Competitive Score**: Each competitor scored 1-100 across 5 dimensions (sales, brand, listing, satisfaction, trend)\n- **Auto-Monitor**: Offers scheduled Quick Check setup after every run\n\n## Install\n\n```bash\nnpx skills add SerendipityOneInc/ZooData-Skills\n```\n\nSelect **Amazon Competitor Intelligence Monitor** when prompted.\n\n## API Key Setup\n\n1. Get a free key at [zoodata.ai/api-keys](https://zoodata.ai/en/api-keys) — 1,000 free credits, no credit card\n2. Set the environment variable:\n   ```bash\n   export ZOODATA_API_KEY='hms_live_xxxxxx'\n   ```\n\n## Example Prompts\n\n- *\"Analyze my competitors for ASIN B0XXXXXXXX in the yoga mat market\"*\n- *\"Run a full competitor scan for keyword 'silicone spatula'\"*\n- *\"Quick check my tracked competitors\"*\n- *\"Who are the top competitors for 'dog harness' and how do I beat them?\"*\n- *\"Monitor competitor price changes and alert me on anomalies\"*\n\n## What You Get\n\n| Section | Description |\n|---------|-------------|\n| ⚔️ Battlefield Overview | Market size, player count, concentration |\n| 📊 Competitor Matrix | Side-by-side comparison of all key competitors |\n| 🏅 Brand Power Ranking | Brand strength scores and market share |\n| 💰 Price Map | Price positioning across competitors |\n| 📈 30-Day Trends | BSR, price, and sales movement |\n| 💬 Review Battle | Rating, sentiment, pain points per competitor |\n| 📋 Listing Audit | Image, bullet, A+ content comparison |\n| 🎯 Battle Strategy | Actionable recommendations to outperform |\n| 🚨 Alerts (Quick Check) | Tiered change detection vs baseline |\n\n## API Endpoints Used\n\n| Endpoint | Purpose |\n|----------|---------|\n| `categories` | Category resolution |\n| `markets/search` | Market context |\n| `products/search` | Product landscape |\n| `products/competitors` | Competitor discovery |\n| `realtime/product` | Live competitor data |\n| `reviews/analysis` | Sentiment & pain points |\n| `products/price-band-overview` | Price band context |\n| `products/price-band-detail` | Detailed price analysis |\n| `products/brand-overview` | Brand concentration |\n| `products/brand-detail` | Per-brand breakdown |\n| `products/history` | Trend analysis |\n\n## Credit Cost\n\nFull Scan: ~28-35 credits. Quick Check: ~5-10 credits.\n\n## Powered By\n\n[ZooData](https://zoodata.ai) — The data infrastructure built for agents. 200M+ Amazon products, 1B+ reviews, real-time signals.\n\nFile v1.1.6:_meta.json\n\n{\n  \"ownerId\": \"kn78k155f6rbh2j8r8yjx8r2e18304q9\",\n  \"slug\": \"amazon-competitor-intelligence-monitor\",\n  \"version\": \"1.1.6\",\n  \"publishedAt\": 1785247259206\n}\n\nFile v1.1.6:references/reference.md\n\n# Market Entry Analyzer — API Field Reference\n\n> Load this file only when you need exact field names or response structure.\n\n## Endpoints Used (11 of 11 — ALL)\n\n| # | Endpoint | Purpose in This Skill | Step |\n|---|----------|-----------------------|------|\n| 1 | `categories` | Find category path for market search | Step 1a |\n| 2 | `markets/search` | Market size, competition metrics, new product rate | Step 1b |\n| 3 | `products/search` | Product supply (100+ via pagination), brand drill, price drill | Step 3, 4b, 7 |\n| 4 | `products/competitors` | Top competitor list | Step 4a |\n| 5 | `realtime/product` | Live detail for Top 5 competitors | Step 4c |\n| 6 | `reviews/analysis` | Consumer pain points, buying factors | Step 6 |\n| 7 | `products/price-band-overview` | Hottest & best opportunity price bands | Step 2a |\n| 8 | `products/price-band-detail` | Per-band SKU/sales/brand/rating breakdown | Step 2b |\n| 9 | `products/brand-overview` | Brand count, CR10, top brand avg price/rating | Step 1c |\n| 10 | `products/brand-detail` | Per-brand SKU/sales/revenue/share ranking | Step 1d |\n| 11 | `products/history` | 30-day price/BSR/sales trend for Top 3 | Step 5 |\n\nBase URL: `https://api.zoodata.ai/openapi/v2`\nAuth: `Bearer $ZOODATA_API_KEY`\nMethod: All POST with JSON body\nAll endpoints return: `{success, data, error, meta}` with `meta.creditsRemaining`\n\n---\n\n## 1. categories\n\n**Request:** (mutually exclusive modes)\n- No params → root categories\n- `categoryKeyword`: String → search by keyword\n- `categoryPath`: List<String> → exact path\n- `parentCategoryPath`: List<String> → child categories\n\n**Response:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `categoryId` | string | Category ID |\n| `categoryName` | string | Category name |\n| `categoryPath` | list | Full path from root |\n| `hasChildren` | bool | Has subcategories |\n| `level` | int | Depth (1=root) |\n| `productCount` | int | Products in category |\n\n---\n\n## 2. markets/search\n\n**Key Request Params:**\n- `categoryPath`: List<String> (e.g. `[\"Pet Supplies\", \"Dogs\"]`)\n- `categoryKeyword`: String\n- `topN`: **String** (`\"10\"` not `10`)\n- `sampleType`: `by_sale_100` / `by_bsr_100` / `avg`\n- `pageSize`: Integer (max 20)\n\n**Key Response Fields:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `totalSkuCount` | int | Market size |\n| `sampleAvgMonthlySales` | float | Demand level |\n| `sampleAvgMonthlyRevenue` | float | Market value |\n| `sampleAvgPrice` | float | Price benchmark |\n| `sampleAvgRating` | float | Quality benchmark |\n| `sampleBrandCount` | int | Brand diversity |\n| `sampleSellerCount` | int | Seller diversity |\n| `sampleFbaRate` | float | FBA adoption (decimal) |\n| `sampleNewSkuRate` | float | New entrant rate (decimal) |\n| `topSalesRate` | float | Product concentration (CR_topN) |\n| `topBrandSalesRate` | float | Brand concentration |\n| `topSellerSalesRate` | float | Seller concentration |\n| `sampleAPlusRate` | float | Margin benchmark |\n\n---\n\n## 3. products/search — Shared Product Object\n\n**Key Request Params:**\n- `keyword`, `categoryPath`, `keywordMatchType` (`mode` is a CLI-only preset — `zoodata.py` expands it into the filter pairs below client-side; it is NOT an API field and returns 422 if sent raw)\n- Filter pairs: `monthlySalesMin/Max`, `priceMin/Max`, `ratingMin/Max`, etc.\n- `pageSize` (max 20), `page`, `sortBy`, `sortOrder`\n- `includeBrands`, `excludeBrands`\n\n**Key Response Fields (per product):**\n| Field | Type | Used For |\n|-------|------|----------|\n| `asin` | string | Product ID |\n| `title` | string | Product name |\n| `brandName` | string | Brand |\n| `price` | float | Price |\n| `monthlySalesFloor` | int | Monthly sales (lower bound) |\n| `monthlyRevenueFloor` | float | Monthly revenue lower bound |\n| `rating` | float | Rating (0-5) |\n| `ratingCount` | int | Review count |\n| `bsr` | int | BSR (NOT `bestsellersRank`) |\n| `fbaFee` | float | FBA cost |\n| `sellerCount` | int | Sellers on listing |\n| `fulfillment` | string | FBA/FBM/AMZ |\n| `listingDate` | string | When listed |\n| `salesGrowthRate` | float | Growth rate |\n| `variantCount` | int | Variants |\n\n---\n\n## 4. products/competitors\n\nSame response as products/search. Different use: discovery by keyword/brand/asin.\nRequest params: `keyword`, `brand`, `asin`, `categoryPath`, `sortBy`, `pageSize`\n\n---\n\n## 5. realtime/product\n\n**Request:**\n- `asin`: String (required)\n- `marketplace`: String (US/UK/DE/FR/IT/ES/JP/CA/AU/IN/MX/BR, default US)\n\n**Response:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `asin` | string | Product ID |\n| `title` | string | Full title |\n| `brandName` | string | Brand |\n| `rating` | float | Current rating |\n| `ratingCount` | int | Current review count |\n| `ratingBreakdown` | object | Star distribution {five_star: {percentage, count}, ...} |\n| `features` | list | Bullet points |\n| `description` | string | Product description |\n| `specifications` | object | Tech specs |\n| `variants` | list | All variants with dimensions |\n| `bestsellersRank` | list | BSR info [{category, rank}, ...] |\n| `buyboxWinner` | object | Buy Box: {price, fulfillment, seller} |\n| `images` | list | All image URLs |\n\n⚠️ Does NOT have: monthlySalesFloor, fbaFee, sellerCount\n\n---\n\n## 6. reviews/analysis\n\n**Request:**\n- `mode`: `\"asin\"` or `\"category\"`\n- `asins`: List<String> (when mode=asin)\n- `categoryPath`: String (when mode=category)\n- `labelType`: filter to specific dimensions. **⚠️ Only ONE value per call — do NOT comma-separate multiple types.** Make separate calls for each labelType needed.\n- `period`: e.g. `\"1m\"` / `\"3m\"` / `\"6m\"` / `\"1y\"` / `\"2y\"`\n\n**labelType values (one per call):** `scenarios`, `issues`, `positives`, `improvements`, `buyingFactors`, `painPoints`, `keywords`, `userProfiles`, `usageTimes`, `usageLocations`, `behaviors`\n\n**Response:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `reviewCount` | int | Sample size |\n| `avgRating` | float | Overall satisfaction |\n| `sentimentDistribution` | object | Positive/neutral/negative ratio |\n| `consumerInsights` | list | Structured insights by dimension |\n| `topKeywords` | list | Trending terms |\n\n**InsightItem:** `{element, labelType, count, reviewRate, avgRating}`\n\n---\n\n## 7. products/price-band-overview\n\n**Request:** Same params as products/search (keyword, category, filters)\n\n**Response:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `sampleSkuCount` | int | Total products analyzed |\n| `sampleMedianPrice` | float | Median price point |\n| `hottestBand` | object | Highest sales share band |\n| `bestOpportunityBand` | object | Highest opportunity index band |\n\n**Band object:** `{bandIdx, bandLabel, sampleBandMinPrice, sampleBandMaxPrice, sampleSkuCount, sampleSalesRate, sampleBrandCount, sampleTop3BrandSalesRate, sampleAvgRating, sampleOpportunityIndex}`\n\n---\n\n## 8. products/price-band-detail\n\n**Response:**\n- `sampleSkuCount`, `sampleTotalMonthlySales`\n- `priceBands`: array of 5 band objects (same structure as above)\n\n---\n\n## 9. products/brand-overview\n\n**Response:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `sampleBrandCount` | int | Total brands |\n| `sampleTop10BrandSalesRate` | float | CR10 concentration (top 10 brands) |\n| `sampleTop10AvgRating` | float | Top 10 brand avg rating |\n| `sampleTop10AvgPrice` | float | Top 10 brand avg price |\n\n---\n\n## 10. products/brand-detail\n\n**Response:**\n- `sampleSkuCount`, `sampleTotalMonthlySales`, `sampleBrandCount`\n- `brands`: array of brand objects\n\n**BrandStats:** `{brandName, sampleSkuCount, sampleGroupMonthlySales, sampleGroupMonthlyRevenue, sampleSalesRate, sampleAvgPrice, minPrice, maxPrice, sampleAvgRating, sampleAvgRatingCount, sampleProducts}`\n\n**sampleProducts:** List of Product objects for this brand within the sample. Each product contains the full Shared Product Object fields (asin, title, price, bsr, monthlySalesFloor, rating, ratingCount, fulfillment, etc). This enables brand-level product matrix analysis without a separate products/search call.\n\n---\n\n## 11. products/history\n\n**Request:**\n- `asins`: List<String> (required)\n- `startDate`: String \"YYYY-MM-DD\" (required)\n- `endDate`: String \"YYYY-MM-DD\" (required)\n⚠️ Does NOT accept `dateRange` — must use startDate + endDate\n\n**Response (array of daily snapshots):**\n| Field | Type | Used For |\n|-------|------|----------|\n| `asin` | string | Product ID |\n| `price` | float | Price on that day |\n| `bsr` | int | BSR on that day |\n| `subBsr` | int | Sub-category BSR |\n| `recentSales` | int | Recent sales count |\n| `updatedAt` | string | Unix timestamp (string) |\n| `createdAt` | string | Unix timestamp (string) |\n\n---\n\n## Cross-Validation Matrix\n\n| Data Point | Primary Source | Validation Source |\n|-----------|---------------|-------------------|\n| Market size | markets/search | products/search (total count) |\n| Brand concentration | brand-overview (sampleTop10BrandSalesRate) | markets/search (topBrandSalesRate) |\n| Price distribution | price-band-detail | products/search (price field) |\n| Competition level | markets (topSalesRate) | brand-detail (top brand shares) |\n| Consumer demand | reviews/analysis | products (sales + growth) |\n| Avg rating quality | markets (sampleAvgRating) | brand-overview (sampleTop10AvgRating) |\n\nFile v1.1.6:skill-card.md\n\n## Description: <br>\nAmazon Competitor Intelligence Monitor helps agents run ZooData-powered Amazon competitor scans or ongoing ASIN monitoring for a defined competitor set. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[apiclaw](https://clawhub.ai/user/apiclaw) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nExternal users and developers use this skill to analyze named Amazon competitors by keyword, ASIN, or brand, then generate competitive reports, battle cards, pricing and review breakdowns, and monitoring alerts. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The skill sends Amazon product research inputs, such as keywords, ASINs, category paths, marketplace/date values, and numeric filters, to ZooData. <br>\nMitigation: Use the skill only for product research data you are comfortable processing through ZooData, and avoid adding unrelated sensitive user-profile text to scan inputs. <br>\nRisk: Full scans and review fallbacks consume ZooData API credits and broad scans can trigger many API calls. <br>\nMitigation: Confirm estimated credit cost before multi-call scans, use quick checks or granular commands under a credit cap, and stop when credentials are invalid or credits are exhausted. <br>\nRisk: The skill stores local monitoring baselines, history, alerts, and temporary review files that may contain competitor research details. <br>\nMitigation: Periodically clean monitor-data and /tmp review work directories when the analysis is sensitive. <br>\n\n\n## Reference(s): <br>\n- [ClawHub skill page](https://clawhub.ai/apiclaw/skills/amazon-competitor-intelligence-monitor) <br>\n- [ZooData Skills homepage metadata](https://github.com/SerendipityOneInc/ZooData-Skills) <br>\n- [ZooData API documentation](https://api.zoodata.ai/api-docs) <br>\n- [ZooData API key setup](https://zoodata.ai/en/api-keys) <br>\n- [API field reference](references/reference.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance] <br>\n**Output Format:** [Markdown reports with tables, command snippets, confidence labels, data provenance, and API usage summaries] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Requires ZOODATA_API_KEY and may create local monitor-data or temporary review work directories during analysis.] <br>\n\n## Skill Version(s): <br>\n1.1.6 (source: server release evidence and skill metadata) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nArchive v1.1.5: 8 files, 46180 bytes\n\nFiles: monitor-data/baseline.json (5818b), monitor-data/config.json (445b), README.md (3145b), references/reference.md (9262b), scripts/zoodata.py (149089b), skill-card.md (2982b), SKILL.md (14605b), _meta.json (157b)\n\nFile v1.1.5:SKILL.md\n\n---\nname: amazon-competitor-intelligence-monitor\ndescription: >\n  Amazon competitor intelligence engine. Produces analytical output focused on\n  a defined set of competitors: either a one-shot deep teardown (Full Scan:\n  28-35 credits, 11 endpoints, battle card, side-by-side comparison,\n  pricing/review/inventory breakdown) OR sustained per-competitor monitoring\n  with alerts (Quick Check: 5-10 credits, realtime polling, baseline diff).\n  Input\n\nArchive v1.1.4: 8 files, 45173 bytes\n\nFiles: monitor-data/baseline.json (5818b), monitor-data/config.json (445b), README.md (3145b), references/reference.md (9262b), scripts/zoodata.py (147843b), skill-card.md (3030b), SKILL.md (13091b), _meta.json (157b)\n\nArchive v1.1.1: 18 files, 44649 bytes\n\nFiles: monitor-data/baseline.json (3436b), monitor-data/config.json (874b), monitor-data/history/2026-04-03T211500Z.json (2524b), monitor-data/history/2026-04-04T011400Z.json (2213b), monitor-data/history/2026-04-04T051400Z.json (3034b), monitor-data/history/2026-04-04T09-15-00Z.json (2189b), monitor-data/history/2026-04-04T211500.json (2194b), monitor-data/history/2026-04-05T011500.json (2873b), monitor-data/history/20260403_091727.json (2117b), monitor-data/history/20260403T171644Z.json (2194b), monitor-data/history/20260407_171624.json (3436b), quick_check.py (5053b), README.md (3145b), references/reference.md (9133b), scripts/apiclaw.py (105922b), skill-card.md (2819b), SKILL.md (7794b), _meta.json (157b)\n\nArchive v1.1.0: 17 files, 43222 bytes\n\nFiles: monitor-data/baseline.json (3436b), monitor-data/config.json (874b), monitor-data/history/2026-04-03T211500Z.json (2524b), monitor-data/history/2026-04-04T011400Z.json (2213b), monitor-data/history/2026-04-04T051400Z.json (3034b), monitor-data/history/2026-04-04T09-15-00Z.json (2189b), monitor-data/history/2026-04-04T211500.json (2194b), monitor-data/history/2026-04-05T011500.json (2873b), monitor-data/history/20260403_091727.json (2117b), monitor-data/history/20260403T171644Z.json (2194b), monitor-data/history/20260407_171624.json (3436b), quick_check.py (5053b), README.md (3145b), references/reference.md (9133b), scripts/apiclaw.py (105921b), SKILL.md (7794b), _meta.json (157b)","readmeExcerpt":"Skill: amazon-competitor-intelligence-monitor Owner: apiclaw Summary: Amazon competitor intelligence engine. Produces analytical output focused on a defined set of competitors: either a one-shot deep teardown (Full Scan: 28-35 credits, 11 endpoints, battle card, side-by-side comparison, pricing/review/inventory breakdown) OR sustained per-competitor monitoring with alerts (Quick Check: 5-10 credits, realtime polling,","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"npx skills add SerendipityOneInc/ZooData-Skills"},{"language":"bash","snippet":"export ZOODATA_API_KEY='hms_live_xxxxxx'"},{"language":"bash","snippet":"npx skills add SerendipityOneInc/ZooData-Skills"},{"language":"bash","snippet":"export ZOODATA_API_KEY='hms_live_xxxxxx'"},{"language":"bash","snippet":"npx skills add SerendipityOneInc/ZooData-Skills"},{"language":"bash","snippet":"export ZOODATA_API_KEY='hms_live_xxxxxx'"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: amazon-competitor-intelligence-monitor\ndescription: >\n  Amazon competitor intelligence engine. Produces analytical output focused on\n  a defined set of competitors: either a one-shot deep teardown (Full Scan:\n  28-35 credits, 11 endpoints, battle card, side-by-side comparison,\n  pricing/review/inventory breakdown) OR sustained per-competitor monitoring\n  with alerts (Quick Check: 5-10 credits, realtime polling, baseline diff).\n  Input: keyword, ASIN(s), or brand — whatever identifies the competitor set\n  to analyze. Output is per-competitor analytical insight tied to that\n  specific set.\n  Use when the user wants focused analysis on identified competitors:\n  a one-shot teardown or an ongoing per-competitor watch.\n  Use when user asks: analyze competitor B07XXX, battle card for ASIN Y,\n  side-by-side competitor teardown, monitor a competitor brand, deep analysis\n  of these 3 competitors, ongoing watch on a defined competitor set.\n  Requires ZOODATA_API_KEY.\nmetadata:\n  version: \"1.1.9\"\n  author: SerendipityOneInc\n  homepage: https://github.com/SerendipityOneInc/ZooData-Skills\n  openclaw: {\"requires\": {\"env\": [\"ZOODATA_API_KEY\"]}, \"primaryEnv\": \"ZOODATA_API_KEY\"}\n---\n\n# ZooData — Competitor Intelligence Monitor\n\n> Know your enemy. Two modes: Full Scan + Quick Check. Respond in user's language.\n\n## Files\n\n| File | Purpose |\n|------|---------|\n| `{skill_base_dir}/scripts/zoodata.py` | **Execute** for all API calls (run `--help` for params) |\n| `{skill_base_dir}/references/reference.md` | Load for exact field names or response structure |\n| `{skill_base_dir}/monitor-data/` | Runtime storage (auto-created): config.json, baseline.json, history/, alerts.json |\n\n## Credential\n\nRequired: `ZOODATA_API_KEY`. Get free key at [zoodata.ai/api-keys](https://zoodata.ai/en/api-keys).\n\n## Capabilities & Data Flow\n\n- **Network**: only `https://api.zoodata.ai` (Bearer `ZOODATA_API_KEY`). Setting `ZOODATA_BASE_URL` to an untrusted host (anything other than `api.zoodata.ai` / `*.zoodata.ai` / localhost) makes the CLI **refuse the request and withhold the key** — the Bearer token is never sent to an untrusted host.\n- **Execution**: bundled shared ZooData CLI `{skill_base_dir}/scripts/zoodata.py` (Python 3, stdlib-only). This skill allows `categories`, `market`, `competitors`, `products`, `product`, `history`, `analyze`, `competitor-analysis`, `check`, plus the review fallback toolkit (`reviews-raw` / `review-tag-prompt` / `review-reduce-prompt` / `review-aggregate`). Do not invoke unrelated subcommands for this skill's tasks — the bundled manifest `{skill_base_dir}/scripts/allowed-commands.json` enforces this: the CLI refuses out-of-scope subcommands with a structured `COMMAND_NOT_ALLOWED` error before any API request.\n- **Local files**: a private temporary working dir (created with `mktemp -d`, removed when the fallback completes) during the review fallback; reads the optional credential store `~/.zoodata/config.json`.\n- **Sent to the API**: keywords, categor"},{"path":"README.md","content":"# Amazon Competitor Intelligence Monitor — ZooData Agent Skill\n\n> Know your enemy. Full Scan + Quick Check. Always watching.\n\n## What This Skill Does\n\nDeep competitor intelligence with two operational modes. **Full Scan** delivers a complete competitive landscape — competitor matrix, brand ranking, pricing map, review battle, and battle strategy. **Quick Check** polls tracked ASINs against a saved baseline and fires tiered alerts when something changes.\n\n### What Makes This Different\n\n- **Dual-mode**: Full Scan (~28-35 credits) for deep analysis, Quick Check (~5-10 credits) for lightweight monitoring\n- **Three-tier alerts**: 🔴 Critical (price crash, Buy Box lost), 🟡 Watch (FBA switch, rating shift), 🟢 Opportunity (stock-out, listing changes)\n- **Competitive Score**: Each competitor scored 1-100 across 5 dimensions (sales, brand, listing, satisfaction, trend)\n- **Auto-Monitor**: Offers scheduled Quick Check setup after every run\n\n## Install\n\n```bash\nnpx skills add SerendipityOneInc/ZooData-Skills\n```\n\nSelect **Amazon Competitor Intelligence Monitor** when prompted.\n\n## API Key Setup\n\n1. Get a free key at [zoodata.ai/api-keys](https://zoodata.ai/en/api-keys) — 1,000 free credits, no credit card\n2. Set the environment variable:\n   ```bash\n   export ZOODATA_API_KEY='hms_live_xxxxxx'\n   ```\n\n## Data & Privacy\n\n- Each run sends your tracked ASINs, competitor ASINs, keywords, category paths, and marketplace/date/numeric filters to the ZooData API (`api.zoodata.ai`). With scheduled Quick Check monitoring enabled, this happens on a recurring, unattended basis.\n- Nothing else is transmitted: no budget, seller-account, or free-text profile data leaves your machine.\n- Local state: baselines, history, and alert files under the skill's `monitor-data/` folder persist between runs for change detection. Delete the folder anytime to reset monitoring and remove the retained data.\n- Scheduled monitoring is opt-in — the skill asks for explicit confirmation before enabling recurring runs. Every API call consumes account credits.\n\n## Example Prompts\n\n- *\"Analyze my competitors for ASIN B0XXXXXXXX in the yoga mat market\"*\n- *\"Run a full competitor scan for keyword 'silicone spatula'\"*\n- *\"Quick check my tracked competitors\"*\n- *\"Who are the top competitors for 'dog harness' and how do I beat them?\"*\n- *\"Monitor competitor price changes and alert me on anomalies\"*\n\n## What You Get\n\n| Section | Description |\n|---------|-------------|\n| ⚔️ Battlefield Overview | Market size, player count, concentration |\n| 📊 Competitor Matrix | Side-by-side comparison of all key competitors |\n| 🏅 Brand Power Ranking | Brand strength scores and market share |\n| 💰 Price Map | Price positioning across competitors |\n| 📈 30-Day Trends | BSR, price, and sales movement |\n| 💬 Review Battle | Rating, sentiment, pain points per competitor |\n| 📋 Listing Audit | Image, bullet, A+ content comparison |\n| 🎯 Battle Strategy | Actionable recommendations to outperform |\n| 🚨 Alerts (Quick Check) |"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn78k155f6rbh2j8r8yjx8r2e18304q9\",\n  \"slug\": \"amazon-competitor-intelligence-monitor\",\n  \"version\": \"1.1.9\",\n  \"publishedAt\": 1786068472455\n}"},{"path":"references/cli-contract.md","content":"<!-- Canonical source - do not edit copies under amazon-* skill directories directly -->\n\n# ZooData CLI Contract\n\n## Ownership and application\n\nThis file owns the project-wide caller contract before and after every bundled `{skill_base_dir}/scripts/zoodata.py` invocation. Read it before selecting the first command, then apply it after each granular or composite result and before any additional API/tool call, fallback, state write, interpretation, or user-facing report.\n\nIt owns the shared invocation form, command-identity validation, execution-environment permission handling, caller/CLI responsibilities, composite-result reuse, result acquisition, transport-status precedence, terminal-interface classification, retry ownership, and partial-result handling. It does not own skill-specific command allowlists, endpoint request/response fields, business interpretation, scenario selection, conclusion authority, or any user-facing failure/report rendering.\n\n## Invocation interface\n\n1. Invoke the bundled client as `python {skill_base_dir}/scripts/zoodata.py [global options] <subcommand> [subcommand options]` using the active skill's local copy.\n2. Place global options before the subcommand. Treat top-level and subcommand `--help` as the live invocation contract; help inspection makes no API request and consumes no credits.\n3. Use the active skill to select the allowed workflow and command scope. Use this contract to validate and execute that selection; do not let this shared file select a business workflow.\n4. Distinguish API/evidence commands from local-only diagnostic, prompt-rendering, and aggregation commands according to the selected subcommand's help. Do not attribute an API call or credit use to a local-only command.\n5. Credential resolution is owned by the bundled CLI. Invoke it directly; do not inspect local credential stores or pre-resolve, compare, export, or override credential values in the caller.\n\n## Command identity and composite reuse\n\n1. Inspect the bundled CLI's top-level `--help` and the selected subcommand's `--help` before invocation. Execute only an exact literal subcommand exposed by the current client and allowed by the active skill.\n2. Treat API endpoint identifiers and composite result keys as data identities, not CLI command names. Never derive a subcommand from either identity or invent an alias.\n3. Treat a successful composite command's structured output as the evidence bundle for that run. Perform selection, narrowing, transformation, extraction, and formatting locally.\n4. Do not make an additional API call solely to reread, reshape, or narrow evidence already present in the composite bundle.\n5. A granular call after a composite is allowed only for evidence absent from the bundle when the active skill's workflow or an explicit non-terminal fallback requires it.\n6. A keyword-driven composite resolves the working category through a fallback chain and records the outcome in `meta`: `meta.category_source` states how it resolved "},{"path":"references/reference.md","content":"# ZooData API Field Reference\n\n> Load this file only when you need exact field names or response structure.\n\n## ZooData Endpoint Field Reference\n\n> Shared field reference. This skill's workflows use ONLY the subcommands\n> listed in its SKILL.md; the endpoints below are documented for field-name /\n> response-structure lookup, not as a claim that this skill invokes all of them.\n\n| # | Endpoint | Purpose |\n|---|----------|---------|\n| 1 | `categories` | Category path lookup |\n| 2 | `markets/search` | Market size, competition metrics, new-product rate |\n| 3 | `products/search` | Product supply (100+ via pagination), brand/price drill |\n| 4 | `products/competitors` | Top competitor list |\n| 5 | `realtime/product` | Live product detail |\n| 6 | `reviews/analysis` | Consumer pain points, buying factors |\n| 7 | `products/price-band-overview` | Price-band opportunity overview |\n| 8 | `products/price-band-detail` | Per-band SKU/sales/brand/rating breakdown |\n| 9 | `products/brand-overview` | Brand count, CR10, top-brand avg price/rating |\n| 10 | `products/brand-detail` | Per-brand SKU/sales/revenue/share ranking |\n| 11 | `products/history` | 30-day price/BSR/sales trend |\n\nBase URL: `https://api.zoodata.ai/openapi/v2`\nAuth: `Bearer $ZOODATA_API_KEY`\nMethod: All POST with JSON body\nAll endpoints return: `{success, data, error, meta}` with `meta.creditsRemaining`\n\n---\n\n## 1. categories\n\n**Request:** (mutually exclusive modes)\n- No params → root categories\n- `categoryKeyword`: String → search by keyword\n- `categoryPath`: List<String> → exact path\n- `parentCategoryPath`: List<String> → child categories\n\n**Response:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `categoryId` | string | Category ID |\n| `categoryName` | string | Category name |\n| `categoryPath` | list | Full path from root |\n| `hasChildren` | bool | Has subcategories |\n| `level` | int | Depth (1=root) |\n| `productCount` | int | Products in category |\n\n---\n\n## 2. markets/search\n\n**Key Request Params:**\n- `categoryPath`: List<String> (e.g. `[\"Pet Supplies\", \"Dogs\"]`)\n- `categoryKeyword`: String\n- `topN`: **String** (`\"10\"` not `10`)\n- `sampleType`: `by_sale_100` / `by_bsr_100` / `avg`\n- `pageSize`: Integer (max 20)\n\n**Key Response Fields:**\n| Field | Type | Used For |\n|-------|------|----------|\n| `totalSkuCount` | int | Market size |\n| `sampleAvgMonthlySales` | float | Demand level |\n| `sampleAvgMonthlyRevenue` | float | Market value |\n| `sampleAvgPrice` | float | Price benchmark |\n| `sampleAvgRating` | float | Quality benchmark |\n| `sampleBrandCount` | int | Brand diversity |\n| `sampleSellerCount` | int | Seller diversity |\n| `sampleFbaRate` | float | FBA adoption (decimal) |\n| `sampleNewSkuRate` | float | New entrant rate (decimal) |\n| `topSalesRate` | float | Product concentration (CR_topN) |\n| `topBrandSalesRate` | float | Brand concentration |\n| `topSellerSalesRate` | float | Seller concentration |\n| `sampleAPlusRate` | float | Margin benchmark |\n\n---\n\n## 3. products/search — Shar"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":2238,"uniquenessScore":42,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T09:28:49.759Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T09:28:49.759Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T11:54:22.186Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}