Shopify inventory export cleaner skill

Shopify Inventory Export Cleaner

Clean messy Shopify CSV exports — fix encoding issues, forward-fill sparse product/order fields, strip whitespace, and flag data quality problems. Outputs a drop-in replacement CSV and a markdown audit trail.

When to use this skill

Activate when the user:

• Has a Shopify CSV export that needs cleaning before analysis
• Mentions encoding problems, blank fields, or messy data in a Shopify export
• Asks about forward-filling, deduplication, or normalizing Shopify exports
• Mentions Excel corrupting their Shopify CSV

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

Any of these three Shopify export formats (auto-detected by column signatures):

Type	Export path	Key columns
Products CSV	Admin → Products → Export	Handle, Title, Variant SKU, Variant Price
Orders CSV	Admin → Orders → Export	Name, Email, Lineitem sku, Lineitem quantity, Created at
Inventory CSV	Admin → Products → Inventory	Handle, Title, SKU, On hand

Running the cleaner

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_export_cleaner.py" \
  --input products_export.csv \
  --output-dir ./cleaned

All flags

Flag	Default	Description
--input	(required)	Path to the Shopify CSV export to clean
--output-dir	./cleaned	Output directory
--type	auto	File type: products, orders, inventory, auto
--no-forward-fill	off	Skip forward-fill of product/order fields
--strict	off	Exit non-zero on errors by default; accepts warnings or all
--utc-dates	off	Normalize dates to UTC (default: preserve original timezone)
--dry-run	off	Preview changes without writing output files

Examples

Clean a products export:

python "$SKILL_DIR/scripts/inventory_export_cleaner.py" \
  --input products_export.csv \
  --output-dir ./cleaned

Clean an orders export without forward-fill:

python "$SKILL_DIR/scripts/inventory_export_cleaner.py" \
  --input orders_export.csv \
  --no-forward-fill

Strict mode (fail CI if issues detected):

python "$SKILL_DIR/scripts/inventory_export_cleaner.py" \
  --input products_export.csv \
  --strict

Preview changes without writing files:

python "$SKILL_DIR/scripts/inventory_export_cleaner.py" \
  --input products_export.csv \
  --dry-run

Convert order timestamps to UTC explicitly:

python "$SKILL_DIR/scripts/inventory_export_cleaner.py" \
  --input orders_export.csv \
  --utc-dates

Output

Two files on normal runs:

1. {original_name}_cleaned.csv — Drop-in replacement with same column structure. Encoding fixed, whitespace stripped, empty rows removed, product/order fields forward-filled, and location names normalized. Orders keep their original timezone unless --utc-dates is used.

2. {original_name}_audit.md — Markdown audit listing every change applied and every issue flagged. Human-readable, version-controllable.

With --dry-run, the cleaner prints the summary and full audit preview but does not write either file.

What gets auto-fixed vs. flagged

Auto-fixed (safe, deterministic transformations):

• UTF-8 BOM removal and LF line ending normalization
• Smart quote normalization (curly → straight)
• Header and value whitespace stripping
• Empty row removal
• Forward-fill of product/order-level fields (unless --no-forward-fill)
• Date normalization to ISO 8601 UTC when --utc-dates is used (orders)
• Location name normalization (inventory)
• Transparent non-UTF-8 decoding (cp1252 / latin-1) with UTF-8 output

Flagged only (requires merchant judgment):

• Blank SKUs, duplicate SKUs
• Missing cost price, zero price variants
• Inventory tracking inconsistencies
• Blank lineitem SKUs (often intentional)
• Negative inventory (oversold)
• Non-numeric values in numeric columns
• Non-contiguous Handle groups (likely Excel sorting)
• Unparseable order dates

Presenting results

After the script runs:

1. Ask about intent first — "Are you cleaning this for analysis (ABC, Dead Stock, etc.) or for re-import into Shopify?"
2. For analysis, confirm the default forward-fill is correct and the cleaned file is ready for the user’s next step.
3. For Shopify re-import, recommend --no-forward-fill to preserve Shopify's sparse variant format. Note that dates stay in the original timezone by default; use --utc-dates only when explicit UTC normalization is needed.
4. Lead with the change count — how many things were fixed automatically.
5. Highlight any flagged issues that need merchant attention, especially blank SKUs and duplicate SKUs.
6. If flags include non-contiguous Handle groups, warn: "Your file appears to have been sorted in Excel — the cleaning is correct, but check for other unintended modifications."
7. Point to the audit report for the full change log.
8. Reference reference.md for background on why Shopify exports are messy.

Multi-file workflows

This cleaner processes one file at a time. If the user has multiple Shopify exports, clean each file separately and keep the resulting files clearly named.

If the user plans to do more analysis afterward, offer to clean the additional exports they already have available, but do not assume any other skill is required.

Edge cases

• Already-clean file: Reports zero changes, still writes output files
• Single-variant products: Forward-fill has no effect (only one row per handle)
• All variants missing SKU: Flags all of them — the merchant needs to add SKUs in Shopify admin
• Non-Shopify CSV: Auto-detection fails; use --type to force, or the script exits with a clear error
• Excel-saved CSV with BOM: Handled automatically — this is the most common encoding issue
• --no-forward-fill for analysis workflows: Variant rows will keep blank product titles. Many downstream analyses will still be numerically correct, but outputs may be less readable. For analysis use, prefer the default (forward-fill enabled).