swads-video-product-analysis/SKILL.md

---
name: swads-video-product-analysis
description: Generate a read-only SW Ads Script Daily Report from the latest seven complete business days, recompute commerce-video CTR and order conversion by product, identify changing creative patterns, and dynamically output exactly three scripts adaptable to every product. Use for high-converting video analysis, per-product CTR/CVR, hooks, creative recommendations, or reusable scripts. Do not use for changing campaigns, budgets, targets, product anchors, or creative delivery.
---

# SW Ads Script Daily Report

Produce an evidence-backed creative analysis from `swads` read data. Never mutate account or delivery state.

## Preconditions and scope

1. Confirm the `swads` MCP is available and call `swads_whoami`.
2. Use the current account unless the user names another visible account. Apply its reporting timezone and currency.
3. Read `metrics_catalog` before querying. Do not guess metric or dimension names.
4. Default to the seven most recent **complete** business days. Use explicit `date_from` and `date_to` so incomplete today is excluded. Honor a user-specified window exactly, but flag incomplete current-day data.
5. If the user supplied product IDs, restrict the analysis to them. Otherwise analyze every product with video delivery in the window.
6. Call the read-only commerce product-list tool and map every `creative_product_id` to its current `product_name`. In Chinese output, translate each resolved product name into concise, natural Chinese for the **商品** column; remove redundant marketplace terms such as repeated “Ready Stock”, “Kitchenware”, hashtags, and duplicated keywords, but preserve material, capacity, size, piece count, and core product type. Keep the original platform `product_name` and numeric ID in JSON/HTML metadata for traceability. In non-Chinese output, use a concise truthful name in the report language.
7. If a product name cannot be resolved after a reasonable retry, derive a concise category description from consistent, specific evidence in that product's video titles and use it directly in the **商品** column (for example `1.4L 滤油壶` or `304 不锈钢 24cm 汤锅`). Preserve material, capacity, size, piece count, and core product type only when the titles support them. In JSON/HTML metadata, keep the numeric product ID, set the original platform `product_name` to `null`, and record that the display name was inferred from video titles. If title evidence is absent, contradictory, or too generic, use `未命名商品（ID末5位）`. Never silently merge distinct product IDs, even when their inferred category descriptions are identical.

## Query and normalization

Query `creative_breakdown` with a sufficiently high limit and at least:

- Dimensions: `external_creative_id`, `external_creative_name`, `creative_identity_kind`, `creative_creator_name`, `creative_product_id`.
- Metrics: `spend`, `gross_revenue`, `orders`, `product_impressions`, `product_clicks`.

Exclude zero-spend rows when the question concerns delivered performance. Remove rows whose identity is `product_card` or whose ID begins with `product_card:`; the report is about videos.

Save the semantic-query JSON response when deterministic aggregation is useful, then run:

```bash
python3 scripts/aggregate_video_products.py query.json --product-id ID --top 5
```

Repeat `--product-id` for multiple requested products. Omit it for all products.

The helper recomputes ratios from aggregate numerators and denominators:

- video CTR = total product clicks / total product impressions
- video order conversion rate = total platform-attributed orders / total product clicks
- ROAS = total platform-attributed gross revenue / total spend
- cost per order = total spend / total platform-attributed orders

Return `null`/`N/A` when a denominator is zero. Never average row-level ratios.

## Example

For a synthetic end-to-end example, read [examples/README.md](examples/README.md). It includes a sample `creative_breakdown` response, deterministic product aggregation, and a rendered Script Daily Report in HTML and PNG. Use it to understand the workflow and artifact shape only; never reuse its example scripts or metrics in a live report.

## Interpretation

- Treat TikTok orders and GMV as platform-attribution evidence, not causal incrementality.
- Order conversion may exceed 100% because orders and product clicks can follow different attribution paths or windows. Call it directional in that case; do not present it as a strict funnel rate.
- Separate scale from efficiency. High ratios on small spend or few orders are uncertain.
- Compare products on CTR and order conversion together:
  - low CTR + low conversion: hook and offer/product fit both need work;
  - high CTR + low conversion: creative attracts interest, but proof, price, product page, stock, shipping, or checkout may block purchase;
  - low CTR + high conversion: qualified viewers buy, but the opening or visual clarity limits reach;
  - high CTR + high conversion: preserve the winning promise and generate controlled variants.
- Use titles and metrics only as evidence for likely messaging. Do not claim to have watched a video unless a playable source or existing multimodal analysis was actually inspected.
- When video access is unavailable, label hook, shot, and plot observations as hypotheses to test.

## Script Daily Report output

Call the deliverable **脚本日报** in Chinese output and **Script Daily Report** in English output. Do not call it merely 日报 or Daily Report.

The primary deliverable is an image. Write a self-contained responsive `script-daily-report.html`, render it as a full-page `script-daily-report.png`, visually inspect the PNG, and iterate if text is clipped, unreadable, or poorly spaced. Use a restrained SW Ads/Wise-style green palette, strong numeric hierarchy, compact product tables, and three clearly separated script cards. Keep a normalized `report-data.json` and the HTML as supporting artifacts, but lead the final response with and visibly embed/link the PNG. If no browser renderer is available, deliver HTML and state clearly that PNG rendering was unavailable.

Default output directory: `~/swads-reports/script-daily/YYYY-MM-DD_to_YYYY-MM-DD/`. Never place credentials or unrelated account data in the artifacts.

For every product in scope, label the product identifier column **商品** in Chinese output, not **商品 ID**:

1. Aggregate video count, impressions, clicks, CTR, orders, order conversion, spend, revenue, ROAS, and cost per order.
2. The strongest videos by order volume, with efficiency and sample-size context.
3. A concise diagnosis of the main creative or conversion constraint.
4. One reusable recommendation tied to the observed data.

After the product analysis, output **exactly three** 12–20 second scripts reusable across every product in the report. Do not write a separate script for each product.

The three scripts must change with the latest seven complete business days of material evidence. Before writing them:

1. Rank recent videos using both scale and efficiency: orders, spend, CTR, order conversion, and ROAS.
2. Extract the recurring hooks, promises, use cases, creator styles, and proof mechanisms from videos with enough evidence.
3. Identify underused opportunities and recent failure patterns such as high CTR with weak conversion or high spend with no orders.
4. Select three distinct script structures that best respond to that week's evidence. Candidate structures include problem/solution, proof test, comparison, objection handling, comment reply, demonstration challenge, price/value breakdown, life scenario, before/after, or creator testimonial. Do **not** force the same three structures every run.

For each script, state which seven-day evidence inspired it and what hypothesis it tests. Use replaceable fields such as `[商品]`, `[核心痛点]`, `[可见证明]`, `[结果]`, and `[CTA]`. Include a 0–3 second visual/verbal hook, shot-by-shot timeline, optional spoken copy/on-screen text, visible proof, outcome, and low-pressure CTA. Provide a compact mapping table showing how each product category should substitute the fields, while keeping the number of full scripts exactly three.

If titles or playable sources do not support a reliable content conclusion, label the proposed hook or plot as a test hypothesis. Never repeat last week's scripts merely because they are present in prior output; derive them again from the current seven-day query.

Prefer proof that matches the product: capacity tests, before/after, filtration, non-stick demonstrations, durability, safety, portion size, cleanup, compatibility, or price/value breakdown. Avoid generic claims unsupported by platform facts.

When many products are present, start with a compact comparison table, then keep each product section short. End with cross-product patterns reusable across the creative program.

## Safety

This workflow is read-only. Put any recommendation involving budget, enable/disable status, ROI targets, pinning/removing creatives, product anchors, or publishing under **Requires human confirmation**. Never execute it.