shopify-theme-validator
A Claude Code skill that validates Shopify themes before they break on save
Documentation
shopify-theme-validator
Validate a Shopify theme before upload and catch the defects Shopify's own theme-check misses.
The problem
Shopify's own validator, theme-check, does not catch everything that breaks an upload. The defects it misses are the ones that cost hours:
- A block name over 25 characters. Shopify rejects it on save, and a long block name once made an upload silently drop two files, with no error shown.
- A duplicate setting
idinside a section or block settings array. theme-check only checkssettings_schema.json. - A hardcoded price, such as $49.99, written literally in code instead of going through the money filter.
- Bare
structured_datathat renders as visible text on the page. - Placeholder copy left in the theme, such as "Sample product" or "$00.00".
This skill teaches the agent the hard rules learned from real theme work, where each rule is a failure that already happened once. They are the same rules that caught the v1.2.1 upload defect, where two long block names dropped templates/product.json and sections/main-product.liquid.
What is in the free skill
shopify-theme-validator/SKILL.md: the hard rules with the exact Shopify error strings, what theme-check catches and what it misses, how to run the validator, the upload workflow, a worked hero banner example, and a troubleshooting table.shopify-theme-validator/references/theme-check-rules.md: the full rule reference, with the sources for every rule (theme-check 3.24.0, the project's own validator, the v1.2.1 defect).shopify-theme-validator/INSTALL.md: install steps for Claude Code, Codex CLI, Cursor, and Claude.ai.shopify-theme-validator/examples/hero-banner.liquid: the worked example from SKILL.md, a clean hero section that passes the validator.shopify-theme-validator/examples/home.json: a template that uses the hero section.shopify-theme-validator/examples/validator-checklist.md: the pre-delivery checklist.
Install
mkdir -p ~/.claude/skills
cp -r shopify-theme-validator ~/.claude/skills/
See shopify-theme-validator/INSTALL.md for Codex, Cursor, and Claude.ai.
Premium pack
The premium pack adds three things the free skill does not have:
validate.py: a script that checks a theme before upload. It catches block and section names over 25 characters, duplicate setting ids inside any settings array, setting ids namedsize,first, orlastthat collide with Liquid's built-in filters, deprecated image filters (img_urland family), bare structured_data, placeholder copy, hardcoded prices, the default filter-chain trap, layout files missing content_for objects, JavaScript syntax errors, template section references that do not exist, block types a template uses but the section does not define, and stale block_order entries. Python 3, no dependencies.validate.py --fixrepairs duplicate setting ids and rebinds the Liquid references, writing new files underfixed/and never overwriting the input.- A reference library: six fresh generic files in valid theme form, a hero banner section, an image with text section with two block types, a template that uses both, a settings schema, a mega menu section, and a footer section with a
localesobject. - A push-to-unpublished checklist: the steps to push a theme to an unpublished theme, preview it on a real store, check the routes, and publish only after the preview passes. Plus a CLI rescue toolkit: the steps when the Shopify CLI misbehaves, ghost dev servers, stale caches, and a forced fresh login.
Get the premium pack at https://websmartools.com/shopify-theme-validator/ for $15, one-time payment, single-user licence.
Licence
The free skill is MIT licensed. See LICENSE. The premium pack has its own single-user licence and is not open source.