Shopify abc analysis skill

ABC Analysis

Classify SKUs into A/B/C priority tiers based on revenue contribution (Pareto analysis). Produces a classified CSV, Pareto curve chart (PNG), and a formatted PDF report — all three, every run.

When to use this skill

Activate when the user:

• Has sales or inventory data and wants to understand which SKUs drive revenue
• Asks about SKU prioritization, revenue concentration, or Pareto/80-20 analysis
• Wants to identify top-performing products, dead stock candidates, or inventory tiers
• Has Shopify product/order CSVs and wants inventory insights

Finding the user's data

Before running the script, prefer explicit paths the user already provided. Only search for files when the path is missing or ambiguous.

1. If the user already gave file paths, use those directly.
2. If the user says "somewhere in my files", search for Shopify exports:
   • Look for files matching orders_export*.csv, Orders*.csv in the current directory and common locations (~/Downloads, ~/Desktop)
   • Shopify exports typically have columns: Name, Email, Lineitem sku, Lineitem quantity, Lineitem price
   • Products exports have columns: Title, Variant SKU, Variant Price
3. If multiple plausible CSVs are found, list them and ask the user to confirm which is the orders file
4. If no CSVs are found, tell the user how to export from Shopify:
   • Orders: Shopify Admin → Orders → Export → CSV for Excel/Numbers/other spreadsheet programs
   • Products: Shopify Admin → Products → Export → All products

Prerequisites

Python 3.9+ is required. Install dependencies before the first run:

pip install pandas>=2.0 matplotlib>=3.7 reportlab>=4.0

If pip install fails

Error	Fix
permission denied	Use pip install --user pandas matplotlib reportlab
pip: command not found	Try pip3 install or python3 -m pip install
externally-managed-environment (Debian/Ubuntu)	Create a venv: python3 -m venv .venv && source .venv/bin/activate && pip install pandas matplotlib reportlab
Module still not found after install	Confirm the Python running the script matches where pip installed: which python3 and which pip3 should share a prefix

Alternatively, if you have resolved the installed skill root, install from the bundled requirements file:

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

Set SKILL_DIR to the installed skill directory in your environment before using that command.

Input

The skill needs sales data with SKU identifiers and revenue (or quantity) information.

Shopify exports (auto-detected)

• Orders CSV (required): Shopify Admin → Orders → Export. The script detects columns Lineitem sku, Lineitem quantity, Lineitem price automatically.
• Products CSV (optional): Shopify Admin → Products → Export. Used to enrich results with product titles. Detected via Title, Variant SKU columns.

Generic CSVs

Any CSV with SKU and revenue/quantity columns works. Use --sku-col and --revenue-col to specify column names if auto-detection fails.

The script also auto-detects a date column (looking for Created at, Date, Order Date, order_date) for two purposes:

• Period filtering: --period requires a date column to filter by days lookback
• New product detection: SKUs with their first sale in the last portion of the analysis window are flagged as potentially misclassified

If no date column is found, period filtering is skipped and new product detection falls back to a generic caveat.

Running the analysis

Resolve the installed skill root first. The exact path depends on where the skill was installed in the current environment.

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

python "$SKILL_DIR/scripts/abc_analysis.py" \
  --orders <path-to-orders-csv> \
  --products <path-to-products-csv> \
  --output-dir ./abc-output

All flags

Flag	Default	Description
--orders	(required)	Path to orders/sales CSV
--products	—	Path to products CSV (for title enrichment)
--output-dir	./abc-output	Directory for output files
--thresholds	80,95	A/B cumulative % split points
--period	all data	Days lookback filter (e.g., 90 for last 90 days)
--metric	revenue	Classify by revenue or quantity
--sku-col	auto-detect	SKU column name for generic CSVs
--revenue-col	auto-detect	Revenue column name for generic CSVs
--quantity-col	auto-detect	Quantity column name for generic CSVs
--products-sku-col	auto-detect	SKU column name in products CSV (when different from orders)
--json	false	Output structured JSON to stdout instead of human-readable text
--csv-only	false	Skip PNG and PDF generation (faster, CSV only)

Output location

Default output goes to ./abc-output relative to the current working directory. For clarity, prefer placing outputs next to the input files or in a location you can communicate clearly to the user:

--output-dir "$(dirname /path/to/orders.csv)/abc-output"

After the script runs, always tell the user the full absolute path to each output file.

Examples

Shopify exports with 90-day lookback:

python "$SKILL_DIR/scripts/abc_analysis.py" \
  --orders orders_export.csv \
  --products products_export.csv \
  --output-dir ./abc-output \
  --period 90

Generic sales CSV:

python "$SKILL_DIR/scripts/abc_analysis.py" \
  --orders sales_data.csv \
  --sku-col "Item Code" \
  --revenue-col "Total Sales" \
  --output-dir ./abc-output

Custom thresholds (70/90 split):

python "$SKILL_DIR/scripts/abc_analysis.py" \
  --orders orders.csv \
  --thresholds 70,90

Output

The script always produces all three outputs:

1. abc_analysis.csv — Classified SKU list: SKU, Product Title, Tier, Revenue, Units Sold, Avg Unit Price, Revenue %, Cumulative Revenue %
2. abc_pareto.png — Two-panel chart: Pareto curve with A/B/C zone shading (left), tier distribution bars (right)
3. abc_report.pdf — Multi-page report: summary + key findings, charts, tier summary table, full classified SKU table

The script also prints a summary to stdout with tier breakdowns and output file paths.

Presenting results

After the script runs:

1. Lead with the concentration insight from the "Key Insights" block (e.g., "Revenue is highly concentrated: 12 SKUs drive 81% of revenue")
2. Name the top 3 SKUs explicitly — merchants want to know which items matter most
3. Highlight any conditional flags prominently: single-SKU dominance (>40% revenue) or C-tier bloat (>60% of SKUs in C)
4. Present the operational recommendations from the "Recommendations" block — these are the actionable takeaways
5. Show the PNG chart inline if the environment supports images
6. Point the user to the PDF report for the full "Analysis & Recommendations" page with per-tier guidance, caveats, and numbered next steps
7. Point to the CSV for raw data export
8. Reference the bundled reference.md for follow-up questions about ABC methodology or deeper discussion of any recommendation

Edge cases

• No product titles: If --products is omitted, the CSV and PDF will show SKU codes without product names
• Single SKU: Classified as Tier A (100% of revenue)
• Zero-revenue SKUs: Classified as Tier C
• Period filter with no matches: Script exits with an error suggesting a longer period or omitting the filter
• Cancelled/refunded orders: Shopify exports with Financial Status column are automatically filtered to paid/authorized orders. If absent, cancelled orders may inflate revenue — noted in caveats
• Small catalogs (<10 SKUs): A warning caveat notes that tier assignments may not reflect meaningful differences