Shopify Theme Validator
Free skill for Claude Code · MIT licence
Free skill on GitHub Premium pack, $15, on Agensi
Shopify Theme Validator is a skill for Claude Code that validates a Shopify theme before upload and catches the defects Shopify's own theme-check misses. The defects it misses are the ones that cost hours. 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.
Who it is for
Shopify theme developers who build and upload themes, and anyone who has had a theme upload fail, or silently drop files, with no error shown.
The problem
- 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".
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
git clone https://github.com/WebSmartTools/shopify-theme-validator.git mkdir -p ~/.claude/skills cp -r shopify-theme-validator ~/.claude/skills/
See shopify-theme-validator/INSTALL.md in the repo for Codex CLI, Cursor, and Claude.ai.
How to use it
Ask Claude Code to validate a theme before upload. The skill checks the hard rules theme-check misses: block and section names, duplicate setting ids, hardcoded prices, bare structured data, and placeholder copy, then walks the upload workflow only when the theme passes.
Premium pack
The premium pack adds three things the free skill does not have, for $15, one-time payment, single-user licence, on Agensi:
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.
The free skill stays free, MIT licensed. The premium pack has its own single-user licence and is not open source.
Questions
Which AI tools does it work with?
The skill is written for Claude Code. The repo's INSTALL.md has the install steps for Codex CLI, Cursor, and Claude.ai.
Is the free skill really free?
Yes. The free skill is MIT licensed, free forever. The premium pack is $15, one-time payment, single-user licence, and it is not open source.