AI-consumable rules for Shopify Liquid theme development.
A collection of rules that teach AI agents how to write correct Shopify Liquid code, plus Claude Code skills to create more.
AI agents produce incorrect Liquid code without explicit guidance. Shopify's Liquid is full of non-obvious patterns, workarounds for language limitations, and community conventions that don't appear in basic documentation.
Shopify's own Horizon theme includes 43 cursor rules covering accessibility and basic code standards -- but they don't cover advanced Liquid patterns, e-commerce logic, or the workarounds experienced developers rely on. That's the gap this project fills.
Each rule is a standalone markdown file in rules/. Copy any rule into your project's AI context:
- Cursor: copy to
.cursor/rules/ - Claude Code: reference in your
.claude/project context or CLAUDE.md - Other AI tools: include as context/system prompts
Rules follow a consistent format: Problem, Solution, How it works, Variations, Source references, Edge cases, and Related rules. See rules/INDEX.md for the full list.
This repo includes three Claude Code skills that form a rule-creation pipeline:
/discover-rule-topics --> BACKLOG.md --> /quick-rule --> rules/
--> /research-shopify-rule --> rules/
Mines patterns across Shopify themes to find rule-worthy topics. Adds discoveries to rules/BACKLOG.md. Works best when you have themes in shopify-themes/.
The fast path. Creates a rule from official Shopify documentation and well-known patterns. 3 phases: Scope, Draft, Finalize. Works without any local themes.
The deep path. Researches patterns across multiple themes, compares approaches, ranks by quality, then produces a thorough rule document. 5 phases: Scope, Research, Analysis, Draft, Finalize. Best with themes in shopify-themes/.
The shopify-themes/ directory is where you put Shopify themes as research material. It starts empty -- add whatever is useful for your research:
- Official themes (recommended starting point):
git clone https://github.com/Shopify/dawn.git shopify-themes/dawn git clone https://github.com/Shopify/horizon.git shopify-themes/horizon - Third-party themes from the Shopify Theme Store or theme developers
- Your own production themes with battle-tested patterns
- Individual
.liquidfiles -- even a single snippet with an interesting pattern is useful
Theme contents are gitignored and never committed to this repo.
Rules can be organized into category folders. These are recommendations, not enforced -- create whatever categories make sense:
| Category | Covers |
|---|---|
liquid-patterns |
Filter chaining, string-as-array workarounds, assign/capture tricks |
collection-and-filtering |
Faceted filtering, active filter detection, sorting, pagination |
cart-and-checkout |
AJAX cart, free shipping bars, discount logic, line item properties |
product |
Variant selection, media galleries, inventory status, price comparison |
navigation |
Breadcrumbs, mega menus, mobile nav, pagination |
metafields |
Metafield reading, metaobject traversal, hierarchical structures |
performance |
Lazy loading, render optimization, conditional asset loading |
theme-architecture |
Section/block design, settings schema, template strategies |
css-patterns |
Custom properties, cascade layers, Liquid-generated CSS |
javascript-patterns |
Web Components, pub/sub, AJAX wrappers, Section Rendering API |
project-config |
ESLint, Prettier, theme-check, CI/CD, Shopify CLI |
html-patterns |
Data attributes, semantic markup, web component markup |
See CONTRIBUTING.md for how to discover topics, create rules, and submit PRs.