---
name: amazon-listing-studio
description: 'Generates market-validated, conversion-ready Amazon listings from product photos and specification sheets. Automates style strength/weakness analysis, pulls live Amazon market intelligence (SIF keyword demand, opportunity screening, competition, and seasonality, plus autocomplete terms across US/UK/DE/FR), and delivers a complete optimized listing — title, highlights, 5 bullet points, description, backend search terms, Q&A, and A+ content — as a polished Excel workbook. Use when the user provides product images (e.g., photo frames, home decor) with parameters and asks to create or optimize an Amazon listing, evaluate a style''s market viability, or run competitor and keyword analysis.'
metadata:
  icon: ':fluent:frame-28-regular:'
  title: Amazon Listing Optimization Studio
  packageName: '@sober/amazon-listing-studio'
  version: 0.1.1
---

# Amazon Listing Optimization Studio

Produces a complete, market-validated listing from product photos + specifications. Positioning: **a best-practice-driven first-draft generator with market intelligence** — not a performance guarantee; it never promises conversion-uplift numbers.

## Trigger Conditions

- The user provides product images (photo frames / home decor, etc.) with parameters and asks to analyze strengths/weaknesses, generate a listing, or run a market comparison
- The user asks to "turn this product into an Amazon listing", "analyze whether this style is worth pursuing", etc.
- `assets/input-template.xlsx` has been filled in, or parameters are provided in the conversation

## Inputs

- **Required**: 3–5 style images (front / side / back panel / lifestyle scene); brand name; product type; outer frame dimensions; color & finish; material; front panel; target marketplace; target price band
- **Optional**: mat opening / hanging hardware / weight / bundles; competitor ASINs (1–3); negative-review screenshots; cost & profit; existing listing; variation plan; certifications; launch date
- Full field documentation: `references/input-template.md`
- If key required fields are missing (material / panel / hardware, etc. — things images cannot confirm): **first output a "fact sheet" for the user to confirm, then write the copy**; otherwise mark the items as [TBC] in the output

## Execution Workflow

### 1. Receive & Parse
Extract parameters from the conversation / attachments / spreadsheet; parameters that images cannot confirm are recorded as items to verify.

### 2. Visual Analysis
Run `scripts/vision_analyze.ps1 -ImagePath <image> -PromptFile prompts/vision.txt -OutFile <temp md>`.
- Model: qwen3.7-plus (OO hosted LLM; the key is retrieved at runtime and must never be written to disk)
- Output must include a "not confirmable from the image" list; read sample text verbatim (brand name / dimension labels, etc.)

### 3. Fact Sheet
Merge visual results + user parameters into a fact table. Unconfirmed items are marked [TBC]. Key parameters missing → ask the user to confirm before continuing.

### 4. Market Data (label source + date for every data point)
Per `references/data-sources.md`:
- **SIF (Link tool service=sif)**: run `inspect_action` first, then `call_action`; default budget ≈ 7 points per style:
  - `market_get_keyword_demand` (main-marketplace core keyword, 2 pts) → seasonality / market size
  - `market_screen_keyword_opportunities` (main root term, 3 pts) → opportunity keyword list
  - `market_get_keyword_competition` (head terms, 2 pts) → competitive landscape / price band
  - Add `market_get_asin_keyword_signals` (3 pts/ASIN) when competitor ASINs are provided
  - Read the output from `data.result.content[0].text` (a JSON string; requires further parsing)
- **Four-marketplace autocomplete terms** (webfetch completion API, US/UK/DE/FR): validate the local phrasing of size/material terms
- Include user-provided ABA / negative-review / ad screenshots in the analysis

### 5. Positioning
Determine: main marketplace keyword (size terms take priority), price-band strategy, ranked differentiation selling points.

### 6. Generate Listing Copy
English output (per-marketplace language for multi-marketplace launches). Apply `references/frame-templates.md` and comply with the hard limits in `references/rules-amazon-2026.md`:
- Title ≤75 characters, highlights ≤125, 5 bullets ≤1000, backend search terms <250 bytes including spaces
- Any unconfirmed parameter is marked [TBC] — never fabricate

### 7. Dual-Algorithm Self-Check
Against the checklist in Section 3 of `references/rules-amazon-2026.md`: A9/A10 (keyword pool / size terms / backend terms / attributes) + AI assistant (bullet semantics / QA / description spec table / images). If the check fails, revise.

### 8. Deliver Excel
Build the data JSON (structure in the header comment of `scripts/build_deliverable.ps1`), run the script to produce the deliverable package, and write it to the **current task artifact directory**, named like `Style-Analysis-and-Full-Listing-<Brand>-<Size>.xlsx`. Default 5 sheets:
1. Style Analysis & Pros/Cons (visuals / features / strengths mapped to selling points / risk areas / [TBC] checklist)
2. Market Comparison (opportunity keywords / competitive landscape / seasonal window / four-marketplace autocomplete terms / price band)
3. Full Listing (title / highlights / 5 bullets / description / backend terms / Q&A / A+, copy-paste ready, with character counts)
4. Launch Self-Check + Image Improvement Checklist (18-point self-check + asset verification)
5. 4-Week Post-Launch Validation Table (ranking / ABA share / conversion / returns, left blank for the user to fill — closes the loop)
- On user request or when time allows: optionally append "US/EU multi-version" and "A+ module copy" sheets

### 9. Iterate
After the user confirms the physical parameters, replace the [TBC] items for the final version; generate multi-marketplace versions on demand.

## Output & Validation

- Deliverables: Excel file + a full listing copy summary in the conversation (title / highlights / bullets / core backend terms)
- Validation: character counts labeled for title / highlights / bullets / backend terms; data source + date labels; [TBC] checklist summary
- Every number must carry its basis (e.g., "weekly search volume, SIF 2026-08-04")

## Red Lines (Never Violate)

1. Never fabricate product parameters; anything not provided by the images or the user is marked [TBC]
2. Never promise conversion-uplift numbers ("improve 20–30%", etc., is marketing copy and must not be cited as fact)
3. Backend search terms: <250 bytes including spaces, spaces only, no brand terms / best / new
4. EU marketplaces must check GPSR / EU responsible person / multilingual requirements (Section 4 of rules-amazon-2026.md)
5. Main image compliance: no text on the sample image, pure white background (provide the spec; reshoots are performed by the user)
6. English copy must be flagged for native-speaker review
7. API keys are used in runtime memory only; never written to files / logs / deliverables

## Failure Handling

| Failure | Handling |
|---|---|
| Vision model errors / doesn't support images | Retry once with glm-5.2 / gpt-5.6-sol; if it still fails, skip the vision step and note it |
| SIF keyword_history errors | Known unavailable endpoint; skip and use demand instead — do not retry repeatedly |
| Other SIF action errors | Log the error, skip that data point and note "data missing"; does not block generation |
| Autocomplete endpoint fails | Skip and note it; fall back to root-term opportunity keyword data |
| Excel COM unavailable | Hand-write the xlsx package (zip + sheet XML), or downgrade to Markdown delivery and explain |
| No images, parameters only | Skip the vision step; go straight to market data + generation |
| All key parameters missing | Stop and ask once (ask all required fields in one go); never guess |