Shopify inventory health skill

Inventory Health Report

Unified per-SKU replenishment analysis. Computes safety stock, reorder point, EOQ, turnover, sell-through, days of stock, and demand variability (XYZ) — then classifies each SKU with an actionable status flag. Three outputs every run (CSV, PNG, PDF).

When to use this skill

Activate when the user:

• Wants to know what to order, when, and how much
• Asks about safety stock, reorder points, or economic order quantity
• Has Shopify exports and wants replenishment recommendations
• Mentions stockout risk, overstock, or inventory planning
• Wants to assess inventory health across their catalog

Prerequisites

Before running, ensure Python 3.9+ is available and install dependencies:

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

Resolve SKILL_DIR to the installed skill root first. If pip install fails due to permissions, try pip install --user -r "$SKILL_DIR/scripts/requirements.txt" or use a virtual environment.

Input

• Orders CSV (required): Shopify Admin → Orders → Export, or any CSV with SKU, quantity, date, and price columns
• Products CSV (optional but recommended): Shopify Admin → Products → Export. Provides stock levels, cost data, and titles. Without it, only demand-side metrics are available.
• Lead time (recommended): Either a global value via --lead-time or a per-SKU column in the products CSV via --lead-time-col. Without lead time, Stockout Risk and Reorder Now flags are unavailable.

Running the report

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/inventory_health.py" \
  --orders orders_export.csv \
  --products products_export.csv \
  --lead-time 14 \
  --output-dir ./health-output

All flags

Flag	Default	Description
--orders	(required)	Orders/sales CSV
--products	—	Products CSV for stock, cost, titles
--output-dir	./health-output	Output directory
--window	90	Analysis window in days
--lead-time	—	Global lead time in days
--lead-time-col	—	Per-SKU lead time column in products CSV
--service-level	0.95	Target service level (0.50–0.9999)
--ordering-cost	—	Fixed cost per order in $ (for EOQ)
--holding-cost	0.25	Annual holding cost as fraction of product cost
--overstock-days	180	Days-of-stock threshold for overstock flag
--sku-col	auto	SKU column (generic CSVs)
--date-col	auto	Date column (generic CSVs)
--quantity-col	auto	Quantity column (generic CSVs)
--revenue-col	auto	Revenue column (generic CSVs)
--cost-col	auto	Cost column (generic CSVs)
--stock-col	auto	Stock column (generic CSVs)
--products-sku-col	auto	SKU column in products CSV when it differs from the orders file
--csv-only	false	Skip PNG and PDF generation (faster, CSV only)

Lead time resolution: When both --lead-time and --lead-time-col are provided, per-SKU values take priority. The global --lead-time fills in SKUs that don't have a per-SKU value.

Examples

Shopify exports with 14-day lead time:

python "$SKILL_DIR/scripts/inventory_health.py" \
  --orders orders_export.csv \
  --products products_export.csv \
  --lead-time 14

90-day window with EOQ:

python "$SKILL_DIR/scripts/inventory_health.py" \
  --orders orders_export.csv \
  --products products_export.csv \
  --lead-time 14 \
  --ordering-cost 25 \
  --window 90

Higher service level for critical inventory:

python "$SKILL_DIR/scripts/inventory_health.py" \
  --orders orders_export.csv \
  --products products_export.csv \
  --lead-time 14 \
  --service-level 0.99

Output

Three files every run:

1. inventory_health_report.csv — Per-SKU metrics: SKU, Title, Status, Demand Variability (X/Y/Z), Avg Daily Demand, Demand Std Dev, CV, Demand Trend %, Current Stock, Days of Stock, Sell-Through %, Turnover Ratio, Lead Time, Safety Stock, Safety Stock Reliability, Reorder Point, EOQ, Revenue, Units Sold, Cost per Unit.

Sorted by status priority (Stockout Risk first), then days of stock ascending within each status. This sort is intentional — the most urgent items appear at the top.

2. inventory_health_chart.png — Two panels: stock position scatter (days of stock vs sell-through, colored by status, sized by revenue) and status distribution bars (% SKUs vs % revenue).

3. inventory_health_report.pdf — Multi-page report: summary with status counts and key findings, analysis and recommendations per status flag, demand variability summary, service level guidance, caveats, numbered next steps, embedded chart, a "SKUs Requiring Action" table, and a "Full Catalog Reference" appendix.

Status flags

Each SKU gets exactly one flag (priority cascade):

Priority	Flag	Condition	Action
1	Stockout Risk	Days of stock < lead time	Emergency order
2	Reorder Now	Stock ≤ reorder point	Standard reorder
3	Overstock	Days of stock > 180 (configurable)	Reduce quantities
4	No Stock	Stock = 0 with active demand	Replenish immediately
5	No Demand	Zero sales in window	Review / discontinue
6	Healthy	None of above	Maintain cadence

Demand variability (XYZ)

Each SKU with active demand gets a demand predictability classification:

Class	CV Range	Meaning	Safety stock reliability
X	< 0.5	Stable, predictable	High — formula accurate
Y	0.5 – 1.0	Variable, possibly seasonal	Moderate — review seasonality
Z	≥ 1.0	Erratic, sporadic	Low — manual review recommended

Presenting results

After the script runs:

1. Check degraded mode first — if any data was missing (no lead time, no stock, no cost), tell the user upfront what's unavailable and why. "Without lead time, I can't flag stockout risk or calculate reorder points."
2. Lead with status flag counts — how many items need action, highlighting urgency
3. For Stockout Risk and Reorder Now items, quote the reorder point and EOQ (if available) as specific quantities: "SKU-123 has 15 units left with a reorder point of 40 — order at least 25 units"
4. Name the top stockout-risk SKUs by revenue — these are urgent
5. Highlight erratic-demand items (Z-class) where safety stock may be unreliable — note that the computed safety stock for these items is a rough guide, not a precise number
6. Present overstock value if cost data was available
7. Note the service level used (default 95%) and mention the A/B/C differentiation recommendation: "For your highest-revenue items, consider re-running at 99%"
8. For Z-class items in Stockout Risk, note that the safety stock number is less reliable — manual judgment needed
9. Show the PNG chart inline if the environment supports images
10. Point to the PDF for full analysis, caveats, and per-SKU detail
11. Reference the bundled reference.md for formula explanations

Degraded modes

The skill works with progressively less data:

• No lead time: Stockout Risk and Reorder Now unavailable. Only Overstock, No Stock, No Demand, and Healthy flags.
• No products CSV: Only demand-side metrics (avg daily demand, demand variability). No stock, sell-through, turnover, or reorder metrics.
• No cost data: EOQ unavailable. All other metrics work.

When presenting orders-only results, acknowledge the limitation upfront: "Without product data, I can show demand metrics (velocity, variability, XYZ classification) but not stock adequacy, sell-through, or reorder calculations. Providing a products CSV would unlock the full analysis."

Edge cases

• Single SKU: Classified normally
• All healthy: Reports zero action items
• Zero demand across all SKUs: Script exits with error (no orders in window)
• Short window (< 180 days): Caveat about seasonal misclassification
• All Z-class (erratic demand): Explicit caveat that safety stock estimates are unreliable across the board