apiclaw-analysis

Files (12)

• README.md
• SECURITY.md
• SKILL.md
• _meta.json
• reference.md · references/
• scenarios-composite.md · references/
• scenarios-eval.md · references/
• scenarios-expand.md · references/
• scenarios-listing.md · references/
• scenarios-ops.md · references/
• scenarios-pricing.md · references/
• apiclaw.py · scripts/

SKILL.md (first lines)

# APIClaw — Amazon Seller Data Analysis

> AI-powered Amazon product research. From market discovery to daily operations.
>
> **Language rule**: Always respond in the user's language. If the user asks in Chinese, reply in Chinese. If in English, reply in English. The language of this skill document does not affect output language.
> All API calls go through `scripts/apiclaw.py` — one script, 5 endpoints, built-in error handling.

## Credentials

- Required: `APICLAW_API_KEY`
- Scope: used only for `https://api.apiclaw.io`
- Resolution order:
  1. **Environment variable** `APICLAW_API_KEY` (preferred, most secure)
  2. **Config file** `config.json` in the skill root directory (fallback)

```json
{ "api_key": "hms_live_xxxxxx" }
```

When user provides a Key, write it to `config.json`. New keys may need 3-5 seconds to activate — if first call returns 403, wait 3 seconds and retry (max 2 retries).

## File Map

| File | When to Load |
|------|-------------|
| `SKILL.md` (this file) | Start here — covers 80% of tasks |
| `scripts/apiclaw.py` | **Execute** for all API calls (do NOT read into context) |
| `references/reference.md` | Need exact field names or filter parameter details |
| `references/scenarios-composite.md` | Comprehensive recommendations (2.10) or Chinese seller cases (3.4) |
| `references/scenarios-eval.md` | Product evaluation, risk assessment, review analysis (4.x) |
| `references/scenarios-pricing.md` | Pricing strategy, profit estimation, listing reference (5.x) |
| `references/scenarios-ops.md` | Market monitoring, competitor tracking, anomaly alerts (6.x) |
| `references/scenarios-expand.md` | Product expansion, trends, discontinuation decisions (7.x) |
| `references/scenarios-listing.md` | Listing writing, optimization, content creation (8.x) |

**Don't guess field names** — if uncertain, load `reference.md` first.

---

## Execution Mode

| Task Type | Mode | Behavior |
|-----------|------|----------|
| Single ASIN lookup, simple data query | **Quick** | Execute command, return key data. Skip evaluation criteria and output standard block. |
| Market analysis, product selection, competitor comparison, risk assessment | **Full** | Complete flow: command → analysis → evaluation criteria → output standard block. |

**Quick mode trigger:** User asks for a single specific data point ("B09XXX monthly sales?", "how many brands in cat litter?") — no decision analysis needed.

---

## ⚠️ Pre-Execution Checklist (MANDATORY for Full Mode)

Before running any Full-mode product selection or market analysis, **complete this checklist**:

- [ ] **Step 1 — Mode Selection:** Check the Product Selection Mode Mapping table below. If ANY of the 14 preset modes matches the user's intent, **USE IT** (`--mode xxx`). Do NOT manually piece together filters when a preset mode exists. Common mappings:
  - Small/lightweight/cheap products → `--mode low-price`
  - New seller / beginner → `--mode beginner`
  - Niche / long-tail → `--mode long-tail`
  - Trending / rising → `--mode emerging`
- [ ] **Step 2 — Realtime Supplement:** Plan to call `product --asin` for the top 3-5 ASINs from results (see Realtime Data Supplementation below).
- [ ] **Step 3 — Review Analysis:** Plan to call `analyze --asins` for top ASINs to get consumer insights (especially painPoints, improvements, buyingFactors).
- [ ] **Step 4 — Output Blocks:** Prepare to include both `📋 Data Source & Conditions` and `📊 API Usage` at the end.

> **Why this exists:** In testing, AI agents repeatedly skipped preset modes, realtime supplements, and review analysis — even though the instructions below clearly describe them. This checklist forces a pause-and-verify before execution.

---

## Execution Standards

**Prioritize script execution for API calls.** The script includes:
- Parameter format conversion (e.g. topN auto-converted to string)
- Retry logic (429/timeout auto-retry)
- Standardized error messages
- `_query` metadata injection (for query traceability)

**Fallback:** If script fails and can't be quickly fixed, use curl directly. Note "using curl direct call" in output.

---

## Realtime Data Supplementation

When `products` or `competitors` returns ASINs in Full-mode analysis, **automatically call `product --asin` for the top 3-5 most relevant ASINs** to get current real-time data.

| Scenario | Supplement? | How many ASINs |
|----------|-------------|----------------|
| Single ASIN lookup (Quick mode) | Already using realtime | — |
| Market overview (no specific ASINs) | ❌ No | — |
| Product selection / competitor analysis | ✅ Yes | Top 3 by sales |
| Risk assessment | ✅ Yes | Target ASIN + top 2 competitors |
| Multi-product comparison | ✅ Yes | All compared ASINs (max 5) |
| Listing analysis | Already using realtime | — |

**Handling data conflicts** — `products`/`competitors` has ~T+1 delay; `realtime/product` is live:

| Field | Use from | Reason |
|-------|----------|--------|
| Price | **realtime** (`buyboxWinner.price`) | Changes frequently |
| BSR | **realtime** (`bestsellersRank`) | Updates hourly |
| Rating / ratingCount | **realtime** | More current |
| Monthly Sales | **products/competitors** | Realtime doesn't have this |
| Profit Margin / FBA Fee | **products/competitors** | Realtime doesn't have this |

When realtime data differs significantly, note it: e.g. "⚡ Price updated: database $29.99 → realtime $24.99 (likely promotion)"

---

## Script Usage

All commands output JSON. Progress messages go to stderr.

### categories — Category tree lookup

```bash
python3 scripts/apiclaw.py categories --keyword "pet supplies"
python3 scripts/apiclaw.py categories --parent "Pet Supplies"
```

Common fields: `categoryName` (not `name`), `categoryPath`, `productCount`, `hasChildren`

From LeoYeAI/openclaw-master-skills, MIT.

More from LeoYeAI/openclaw-master-skills