Shopify dead stock skill

Dead Stock Identifier

Flag dead, slow-moving, and declining SKUs based on sales velocity analysis. Produces a flagged inventory CSV, velocity distribution chart (PNG), and a formatted PDF report with operational guidance — all three, every run.

When to use this skill

Activate when the user:

• Wants to find dead stock, slow-moving inventory, or items losing momentum
• Asks about inventory carrying costs, warehouse space waste, or capital tied up in unsold goods
• Has Shopify product/order CSVs and wants to know what to discontinue, discount, or investigate
• Mentions declining sales velocity, items that stopped selling, or catalog rationalization

Prerequisites

Before running the analysis, 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

The skill needs sales data with dates (to measure velocity) and optionally product data (for stock on hand and cost).

Shopify exports (auto-detected)

• Orders CSV (required): Shopify Admin → Orders → Export. Detected via Lineitem sku, Lineitem quantity, Lineitem price, Created at.
• Products CSV (recommended): Shopify Admin → Products → Export. Provides stock on hand (Variant Inventory Qty), cost (Variant Cost per item), and product titles. Without this, dead stock detection is limited to SKUs that appear in orders.

Generic CSVs

Any CSV with SKU, date, and quantity columns works. Use --sku-col, --date-col, --quantity-col to specify column names if auto-detection fails. Use --cost-col and --stock-col for product data in generic formats.

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/dead_stock.py" \
  --orders <path-to-orders-csv> \
  --products <path-to-products-csv> \
  --output-dir ./dead-stock-output

All flags

Flag	Default	Description
--orders	(required)	Path to orders/sales CSV
--products	—	Path to products CSV (stock, cost, titles)
--output-dir	./dead-stock-output	Directory for output files
--window	90	Analysis window in days
--slow-percentile	10	Velocity percentile for "at risk" tier
--decline-threshold	50	Velocity decline % for "watch" tier
--carrying-cost	—	Annual carrying cost as fraction of product cost (e.g., 0.25)
--csv-only	false	Skip PNG and PDF generation (faster, CSV only)
--sku-col	auto-detect	SKU column name for generic CSVs
--products-sku-col	auto-detect	SKU column name in products CSV (when different from orders)
--date-col	auto-detect	Date column name for generic CSVs
--quantity-col	auto-detect	Quantity column name for generic CSVs
--revenue-col	auto-detect	Revenue/price column name for generic CSVs
--cost-col	auto-detect	Product cost column name for generic CSVs
--stock-col	auto-detect	Stock-on-hand column name for generic CSVs

Examples

Shopify exports with carrying cost analysis:

python "$SKILL_DIR/scripts/dead_stock.py" \
  --orders orders_export.csv \
  --products products_export.csv \
  --output-dir ./dead-stock-output \
  --carrying-cost 0.25

Wider analysis window (180 days):

python "$SKILL_DIR/scripts/dead_stock.py" \
  --orders orders_export.csv \
  --products products_export.csv \
  --window 180

Output

The script always produces all three outputs:

1. dead_stock_report.csv — Flagged SKU list: SKU, Product Title, Risk Tier, Units Sold, Revenue, Days Since Last Sale, Avg Daily Velocity, Current Stock, Days of Stock Remaining, Est. Carrying Cost, Velocity Change %
2. dead_stock_chart.png — Two-panel chart: velocity distribution with risk tier coloring (left), risk tier breakdown bars (right)
3. dead_stock_report.pdf — Multi-page report: summary, analysis & recommendations with per-tier operational guidance, charts, tier summary table, full flagged inventory table

The CSV is sorted by risk tier (Dead first, then At Risk, Watch, Healthy) and within each tier by days since last sale (longest first). This means the most urgent items appear at the top of the file.

Risk tiers

Tier	Definition	Color
Dead	Zero units sold in the analysis window	Red
At Risk	Velocity in the bottom Nth percentile of active SKUs	Amber
Watch	Velocity declined >X% vs prior equivalent period	Yellow
Healthy	Not flagged	Green

Presenting results

After the script runs:

1. Lead with the dead stock % KPI if cost data was provided — this is the single most scannable health metric (e.g., "Dead inventory represents 23% of carrying cost — critical threshold")
2. Name the top dead stock items by inventory value (or units if no cost data) — merchants want to know which items to act on first
3. Present the aging breakdown for dead items — this communicates urgency: items 180+ days need immediate disposal action, 91-180 need escalation, 61-90 need intervention
4. Highlight any capital opportunity if carrying cost data is available
5. Present the escalating disposal actions from the PDF — these urgency-graded recommendations are the key differentiator of this tool over flat "you have dead stock" lists
6. Show the PNG chart inline if the environment supports images
7. Point the user to the PDF report for the full "Analysis & Recommendations" page with per-tier guidance, escalating disposal actions, caveats, and next steps
8. Point to the CSV for raw data — note it's sorted by risk tier (Dead first) then days since last sale (descending), so the most urgent items appear first
9. Suggest cross-referencing with ABC Analysis: items flagged here that are Tier A or B in ABC need immediate attention — they were revenue drivers and are now losing momentum
10. Reference the bundled reference.md for follow-up questions about dead stock methodology, SLOB terminology, aging framework, or carrying cost calculation

If no products file was provided: Acknowledge upfront that stock-on-hand, carrying cost, sell-through rate, and days-of-stock are unavailable. Explain what additional insights would be available with product data: "With a products export, I could also show you how much capital is tied up in dead stock, how many days of inventory you're carrying, and sell-through rates."

Edge cases

• No products file: Analysis limited to SKUs in orders; stock on hand and carrying cost unavailable. Noted in caveats.
• Insufficient history for Watch tier: Need 2× the window in order data to detect velocity decline. If unavailable, Watch tier is omitted and noted in caveats.
• All items dead: Script handles gracefully — all SKUs classified as Dead.
• No cost data: Carrying cost columns show as empty; capital opportunity section omitted.
• Single SKU: Classified based on whether it had sales in the window.
• Cancelled/refunded orders: Shopify exports with Financial Status column are automatically filtered to paid/authorized orders. If this column is absent, cancelled orders may inflate velocity — noted in caveats.

Optional follow-up analysis

If the user also wants revenue-priority context, pair this analysis with a separate ABC analysis. Treat that as an optional follow-up rather than a dependency: this skill stands on its own for dead-stock and slow-mover decisions.