# Sku Performance Comparison

> Compare SKU performance across two periods using ABC classification, identify tier movement, detect major risers and declines, review SKU drift over time, and analyze changes in revenue or unit contribution from Shopify or generic CSV exports. Use when an agent needs SKU performance comparison, ABC drift analysis, period-over-period SKU movement, assortment change review, or seasonal SKU shift detection.

- Skill: `useretrace/sku-performance-comparison` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add useretrace/sku-performance-comparison`
- Raw SKILL.md: https://api.skillmd.com/api/skills/useretrace/sku-performance-comparison/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: useretrace (https://skillmd.com/u/useretrace)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/useretrace/sku-performance-comparison

---


# 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:

```bash
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:

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

Preferred explicit-date invocation:

```bash
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:

```bash
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."