Shopify sku performance comparison skill

SKU Performance Comparison

Compare SKU performance across two periods using ABC classification. This skill produces a comparison CSV, a visual summary PNG, and a formatted PDF report on every normal run.

Finding the user's data

Prefer explicit file paths first. Only search for files if the user has not provided usable paths.

1. If the user already gave file paths, use them directly.
2. If the user says the files are somewhere locally, look for plausible Shopify exports such as orders_export*.csv and products_export*.csv.
3. If multiple plausible CSVs exist, list them and ask the user to confirm which one is the orders file.
4. If no orders CSV can be found, tell the user how to export orders from Shopify Admin.

Prerequisites

Python 3.9+ is required.

Install dependencies before the first run:

pip install -r "$SKILL_DIR/scripts/requirements.txt"

Resolve SKILL_DIR to the installed skill directory in the current environment before using that command.

If pip install fails:

• try python3 -m pip install -r "$SKILL_DIR/scripts/requirements.txt"
• if the environment is externally managed, create and activate a virtualenv first

Inputs

Required:

• an orders or sales CSV with SKU, date, and revenue or quantity data
• two explicit periods, or a shorthand window definition

Optional:

• a products CSV for title, vendor, product type, and stock enrichment

Shopify exports

Orders CSV is auto-detected when it contains:

• Lineitem sku
• Lineitem quantity
• Lineitem price
• Created at

Products CSV is auto-detected when it contains:

• Variant SKU
• Title

Generic CSVs

If auto-detection fails, use override flags:

• --sku-col
• --date-col
• --quantity-col
• --revenue-col
• --products-sku-col
• --title-col
• --vendor-col
• --product-type-col
• --stock-col

Running the analysis

Resolve the installed skill root first:

SKILL_DIR="<resolved-installed-skill-dir>"

Preferred explicit-date invocation:

python "$SKILL_DIR/scripts/sku_performance_comparison.py" \
  --orders <path-to-orders-csv> \
  --products <path-to-products-csv> \
  --period-a-start 2024-10-01 \
  --period-a-end 2024-12-31 \
  --period-b-start 2025-01-01 \
  --period-b-end 2025-03-31 \
  --period-a-label "Q4 2024" \
  --period-b-label "Q1 2025" \
  --output-dir ./sku-drift-output

Shorthand equal-window comparison:

python "$SKILL_DIR/scripts/sku_performance_comparison.py" \
  --orders <path-to-orders-csv> \
  --window-days 90 \
  --compare-mode sequential \
  --output-dir ./sku-drift-output

Flags

Flag	Default	Description
--orders	required	Orders or sales CSV
--products	-	Products CSV for enrichment
--output-dir	./sku-drift-output	Output directory
--thresholds	80,95	A/B cumulative split points
--metric	revenue	Compare by revenue or quantity
--period-a-start	-	Period A start date
--period-a-end	-	Period A end date
--period-b-start	-	Period B start date
--period-b-end	-	Period B end date
--period-a-label	derived	Label for period A
--period-b-label	derived	Label for period B
--window-days	-	Shorthand comparison window size
--anchor-date	max order date	Anchor date for shorthand comparisons
--compare-mode	sequential	sequential or previous-year
--sku-col / --date-col / --quantity-col / --revenue-col	auto	Generic order CSV overrides
--products-sku-col / --title-col / --vendor-col / --product-type-col / --stock-col	auto	Generic products CSV overrides
--json	false	Emit structured JSON to stdout
--csv-only	false	Skip PNG and PDF generation

Output

Normal runs produce:

1. sku_performance_comparison.csv
2. sku_performance_comparison.png
3. sku_performance_comparison_report.pdf

The script also prints a concise stdout summary with movement counts, key insights, recommendations, and output file paths.

With --json, the skill still writes the normal output files, and stdout switches to structured JSON with:

• run settings and input filenames
• period-level SKU, line, revenue, and unit counts
• summary movement counts
• headlines, caveats, pattern note, and recommendations
• top declines and top risers
• a ranked preview of the first 25 comparison rows

Use the CSV when a downstream step needs the full per-SKU table. JSON is intentionally bounded so agents can chain on the most important rows without scraping human-readable text.

Presenting results

After the script runs:

1. Lead with the biggest movement headline, not the mechanics.
2. Name the top risers and top declines explicitly.
3. Call out any former A-tier SKU declines early.
4. Treat seasonal language carefully. Say "possible seasonal concentration" unless there is stronger evidence.
5. Point the user to the PNG for a fast visual summary.
6. Point the user to the PDF for the full merchant-facing report.
7. Use reference.md for methodology and caveats when the user asks follow-up questions.

Degraded modes

• No products CSV: the comparison still runs, but product titles, vendor grouping, product type grouping, and stock context may be incomplete.
• Missing financial status fields: Shopify cancellation filtering may be incomplete.
• Small catalogs or short windows: movement is directional, not definitive.
• New SKUs: a SKU may look like a dramatic riser simply because it did not exist in period A.
• SKU remaps: a disappearance plus a new SKU can reflect identifier changes, not a demand shift.

Always keep the core caveat visible:

"This is a two-period comparison, not a forecast. Apparent seasonal patterns should be validated against additional history."