How to Use Claude Code for Shopify Liquid Themes (2026)

Why Claude Code Changes Liquid Theme Work

Ever spent an afternoon renaming a snippet across 40 section files, only to realize you missed three in a language folder? Shopify Liquid has a maintenance problem. Real themes sprawl across sections/, snippets/, templates/, blocks/, config/, and locales/ — with schema JSON pinned inside Liquid files and translation keys miles from where they render. Manual refactors are slow, error-prone, and eat a senior dev's entire Friday.

Claude Code, Anthropic's terminal-based agent, is unusually well-suited to this mess. It reads whole directory trees, edits multiple files atomically, runs the Shopify CLI, parses theme check output, and follows project-specific conventions when you write them down in a CLAUDE.md file. Combined with Shopify's AI Toolkit for Claude Code released in April 2026, it now has first-class access to Liquid objects, filters, and schema references without hallucinating.

This guide is tactical. No "AI will transform development" fluff — just the setup, prompts, and subagent patterns that work on real themes. If you're already familiar with the broader agent workflow, skim the pillar guide to Claude Code for Shopify development for general agent conventions. Everything below is specific to Liquid.

Setting Up Claude Code for a Theme Repository

Before you write a single prompt, get the environment right. A theme repo is not a Next.js app — Claude Code needs different context, and the defaults will mislead it.

Clone the Theme Locally

Pull your theme with the Shopify CLI so Claude Code can read actual files, not scraped copies from the admin. Run shopify theme pull --live to get your published theme or shopify theme pull --theme=<id> for an unpublished version. Commit the result to a private Git repository before you let any agent touch it — this gives you a clean diff target and lets you revert if a refactor goes sideways.

Keep your .gitignore permissive for theme work:

• node_modules/ if you have a Tailwind or bundler layer
• .shopifyrc, .shopify-cli.yml, and any personal CLI auth
• .env files (store IDs, Partner credentials)
• screenshots/ or .DS_Store noise

Install the Shopify AI Toolkit

The toolkit is an MCP (Model Context Protocol) server that exposes Liquid docs, GraphQL schemas, and Shopify CLI operations directly to the agent. Install it globally and register it with Claude Code per Ask Phill's Shopify AI Toolkit walkthrough so your agent stops guessing at filter names and schema settings. Without it, you will occasionally see Claude invent a product.featured_variant (not real) or misremember pagination syntax. With it, grounded answers go up sharply.

Open Claude Code at the Theme Root

Claude Code reads the nearest CLAUDE.md walking up from your cwd. Open your terminal at the theme root — not one level up in a mono-repo, not in sections/ — so the agent has the right scope when you invoke it. PageFly's breakdown of Liquid theme structure covers the canonical folder layout (sections/, snippets/, templates/, config/, locales/) — make sure Claude Code has the whole tree in view.

Your CLAUDE.md for a Liquid Theme

This is the single highest-leverage file in your repo. A good CLAUDE.md turns a generic LLM into a Shopify-native collaborator. Keep it under 200 lines — long files get compressed, and the important rules get lost.

What Belongs in CLAUDE.md

A strong theme-level CLAUDE.md covers five things: stack, conventions, commands, file map, and guardrails. Here's a condensed template:

# Theme: [Brand Name] — Dawn-based custom theme

## Stack
- Shopify Liquid (Online Store 2.0)
- Dawn 15.x as base, heavily customized
- Tailwind CSS v4 via PostCSS build (see `tools/build.mjs`)
- JSON templates, not legacy Liquid templates

## Conventions
- Sections: PascalCase in schema `name`, kebab-case filename
- Snippets: always pass named args, never rely on globals
- Blocks: use `block.settings` over `section.settings` for repeatable UI
- Metafields: read via `product.metafields.custom.<key>` only (never root namespace)
- Translations: every user-facing string uses `{{ 'key' | t }}` — no hardcoded English

## Commands
- `shopify theme dev` — local preview
- `shopify theme check` — lint (must pass with 0 errors)
- `shopify theme push --unpublished` — deploy to a duplicate, never live
- `pnpm css` — Tailwind build

## File Map
- Custom sections live in `sections/custom-*`
- Shared helpers in `snippets/_*.liquid` (underscore prefix = internal)
- App blocks in `blocks/`
- Customer-facing copy in `locales/en.default.json`

## Guardrails
- NEVER push directly to the live theme
- NEVER commit changes from the online code editor without pulling first
- Flag any `{% assign %}` inside a loop — potential performance issue
- Always run `shopify theme check` after multi-file changes

Let the Agent Discover the Rest

You don't need to document every section file. Claude Code will read the tree on demand. What you do need is anything that's not obvious from the code itself — naming prefixes, metafield namespaces, which folder is "legacy and do not touch," and commands the agent should run after edits. Anthropic's guidance on CLAUDE.md files recommends treating it as the onboarding doc you'd hand a new hire.

Refactoring a Dawn Theme Into a Custom Theme

This is where most Shopify theme devs will start. You have a Dawn fork, a client wants custom sections, brand typography, and a bespoke product page. Doing this by hand takes a week. Done with Claude Code, it takes an afternoon — if you scope it right.

Break the Work Into Prompts, Not Epics

Never ask Claude Code to "convert Dawn into a custom theme." Scope it per section. A good first prompt:

Read sections/main-product.liquid. Create a copy at sections/custom-product.liquid with these changes: remove the vendor display, move the price above the title, wrap the add-to-cart in a sticky container on mobile, and add a new block type called trust-badges that accepts up to 4 image + label pairs. Preserve all existing block types. Update the schema name to "Custom Product Main" and the presets entry so it's available in the theme editor.

That's specific, testable, and bounded. The agent edits one file, you review the diff, push to an unpublished theme, and preview. Compare that to a vague "redesign the product page" prompt — which will produce 800 lines of opinionated changes you'll spend two hours unwinding.

Handle the Schema Carefully

Section schemas are the most error-prone part of Liquid refactors. Claude occasionally produces invalid JSON (trailing commas, missing type on settings) or forgets that default values must match the type. Add this line to your CLAUDE.md:

After editing any {% schema %} block, run shopify theme check and fix every error before stopping. Treat schema validation as a gate.

That single instruction eliminates roughly 80% of broken-section headaches. For a deeper look at how to structure reusable sections once they exist, see our guide on building custom Shopify sections.

Keep the Theme Editor Usable

A common refactor trap: Claude strips schema settings because they "aren't used anywhere in the Liquid." But merchants configure those settings through the theme editor, and removing them wipes their customizations. Tell the agent explicitly: "Preserve all existing schema settings unless I call one out by name. Adding new settings is fine; removing them is not."

A Sectioning Workflow That Actually Scales

Online Store 2.0 rewards theme devs who think in blocks and presets, not flat sections. Claude Code is excellent at this kind of structured decomposition — but only if you give it the mental model.

Start From a Visual Spec

Paste the Figma frame description or a screenshot into the prompt, then describe the block structure you want:

Here's the new homepage hero. Build sections/hero-split.liquid with two column blocks (each accepting heading, body, image, CTA label, CTA link) and one optional announcement block above the columns. Use the brand's existing CSS custom properties (--color-brand, --color-surface). No Tailwind classes — this theme uses vanilla CSS. Expose mobile_stack_order as a section setting with choices image_first and text_first.

Use Block Types Liberally

A good theme has many small block types rather than a handful of god-blocks. Claude will default to god-blocks if you don't nudge it — a single "content" block with 15 settings. That's unmaintainable. In your CLAUDE.md, add: "Prefer narrow block types (each doing one thing) over a single configurable block type." Then you'll get heading, body, cta, image blocks instead of a mega-block. This mirrors patterns the Shopify Dawn theme repository uses for its modular sections.

Lock in Presets

Every section should ship with at least one preset so merchants can drop it onto a page without configuring from scratch. Prompt: "Add a presets array with one preset called 'Hero — Default' that fills in realistic placeholder content for all blocks." Claude Code does this well when asked explicitly and skips it when not.

Metafield-Driven Sections Without the Pain

Metafields are the reason Online Store 2.0 is usable for custom storefronts, and they're also where most theme devs slow down. Naming is inconsistent, types are picky, and the Liquid to render them cleanly is verbose. Claude Code handles all of this if you give it the namespace and type up front.

Define the Metafield Contract First

In your prompt, always include the full metafield path and type:

Render the product's size guide from product.metafields.custom.size_guide (type: rich_text_field) inside a new snippet snippets/product-size-guide.liquid. If the metafield is empty, render nothing. If present, render the rich text through the metafield_tag filter and wrap it in a <details> element with summary "Size guide".

Don't Let Claude Guess the Type

If you omit the metafield type, Claude will often render a rich_text_field like a string, producing escaped HTML on the page. Always specify. The Shopify metafields reference lists every type and how to render it.

Build a Metafield Catalog

For larger themes, create a docs/metafields.md file listing every metafield the theme reads: namespace, key, type, where it's used, and what happens if missing. Reference it from CLAUDE.md. This single doc prevents dozens of "is this one the rich text version or the plain text version?" mistakes.

Running theme check With Claude Code

Shopify Theme Check is the official linter for Liquid and JSON inside themes. It catches syntax errors, unused assignments, missing snippets, deprecated tags, and performance problems. Running it manually is fine. Running it through Claude Code unlocks fix-on-save automation.

Let the Agent Run and Parse Output

Give Claude Code permission to run shopify theme check (add it to your .claude/settings.json allowlist) and it will lint proactively after edits. A prompt like:

Run shopify theme check and fix every error in sections/custom-product.liquid. For warnings, list them but don't auto-fix — I'll review each one.

...turns linting from a manual step into part of the edit loop. The tool outputs checks organized by severity, and Claude Code parses them cleanly.

Configure theme-check.yml

A tuned .theme-check.yml is worth the hour of setup. Disable checks that don't match your theme (e.g., ParserBlockingScript if you deliberately inline critical JS) and raise the severity of checks you care most about. Shopify's Theme Check configuration docs list every available check. Claude Code will respect the config file when running the linter — you don't need to tell it to.

Treat theme check as a Gate

In CLAUDE.md, add: "Before marking any task complete, run shopify theme check and confirm 0 errors." This single rule prevents a whole category of "it looks done but the page is broken" problems.

Building a Liquid-Lint Subagent

This is where Claude Code stops being a chat window and starts being an engineering platform. Subagents are specialized agents with their own system prompt, tool allowlist, and context window — defined as markdown files in .claude/agents/. They're ideal for tasks you run repeatedly.

Why a Liquid-Lint Subagent

A dedicated subagent can:

• Run shopify theme check on a targeted file
• Parse errors and warnings into structured output
• Auto-fix safe categories (missing translation keys, unused assignments, spacing)
• Flag unsafe categories (deprecated tags, performance warnings) for human review
• Write a one-line summary for your commit message

Example Subagent Definition

Create .claude/agents/liquid-lint.md:

---
name: liquid-lint
description: Lints a single Liquid file with theme check, auto-fixes safe issues, and reports the rest.
tools: read, edit, bash
---

You are a Shopify theme linting specialist. Your job is to run `shopify theme check` on the file passed to you, fix issues in the "safe auto-fix" list, and report everything else.

Safe auto-fix categories:
- MissingTranslation (add the key with a TODO value)
- UnusedAssign (remove the assignment)
- SpaceInsideBraces (normalize spacing)
- TrailingWhitespace (remove)

Never auto-fix:
- DeprecatedTag (flag for human)
- TemplateLength (flag for human)
- ParserBlockingScript (flag for human)
- AssetUrlFilters (flag for human)

Output format:
## Fixed
- <file>:<line> <rule> — <what you did>

## Needs Review
- <file>:<line> <rule> — <why a human should look>

Always end with the summary line: "Lint complete: N fixed, M flagged."

Invoke it with @liquid-lint sections/custom-product.liquid and it runs in an isolated context, returns only the summary, and keeps your main conversation clean. Anthropic's subagent documentation covers the full spec, and the awesome-claude-code-subagents repo has 100+ patterns worth borrowing from.

When to Use Subagents vs Slash Commands

Subagents win when the task needs an isolated context window (long outputs, many tool calls). Slash commands win for simple, repeatable prompts. For theme work, you probably want both — a /new-section command that kicks off the scaffolding prompt, and a @liquid-lint subagent that runs after every substantial edit.

Prompts That Actually Work on Real Themes

Prompts are where most people fail. Below are battle-tested patterns for common theme tasks. Copy, adapt, ship.

New Section From a Description

Create sections/testimonial-grid.liquid. It should render up to 6 testimonial blocks in a 3-column grid (stacking to 1 column below 600px). Each block has: quote (textarea), author name (text), author title (text), author photo (image_picker). Include section settings for heading, subheading, background color, and column count (choices: 2, 3, 4). Add one preset with realistic placeholder content. Use the theme's existing spacing tokens. Run shopify theme check and fix any errors.

Dawn-to-Custom Port

Copy sections/main-product.liquid to sections/custom-product-v2.liquid. Remove the Dawn "product_info" merge tag pattern. Replace block rendering with an explicit switch on block.type (title, price, variant_picker, quantity_selector, buy_buttons, description). Preserve all existing block types and settings. Don't touch the schema tag or class fields.

Metafield Rendering

In snippets/product-specs.liquid, render the metafield product.metafields.custom.specifications (type: list.single_line_text_field) as a <dl> element where each value is split on the first colon into <dt> and <dd>. If the metafield is empty or missing, render nothing. No extra markup.

Refactoring Pass

Read every file in sections/ and list: (1) sections that use {% assign %} inside a {% for %} loop, (2) sections with schemas over 200 lines, (3) sections that hardcode English copy without the | t filter. Output as a table. Do not edit anything.

Translation Key Migration

For every hardcoded English string in sections/custom-*.liquid, replace with a translation filter call, add the key to locales/en.default.json with the original English as the value, and add the key to locales/es.json with a TODO value. Preserve HTML tags inside strings by using {{ 'key_html' | t }} pattern where appropriate.

Performance Audit

Read sections/ and snippets/. Identify any Liquid code that: runs DB queries inside loops (e.g., collection.products referenced in a loop over collections), uses all_products (deprecated), or fetches more than 50 items without pagination. Output file, line number, the problematic pattern, and a suggested fix. Don't edit yet.

These prompts work because they're specific, testable, and bounded. Vague prompts produce vague diffs. Agencies like Flagship have published similar patterns from their own theme work — the common thread is always specificity.

Shopify CLI Workflows Claude Code Handles Well

The Shopify CLI is the safest way to deploy theme changes. Claude Code can run every command in the CLI, but some workflows benefit more from agent orchestration than others.

Safe to Automate

• shopify theme pull with a specific theme ID (fetch changes from the online editor)
• shopify theme check with any flag combination
• shopify theme push --unpublished to create or update a duplicate
• shopify theme dev to start the local preview (backgrounded)
• shopify theme list to find the right theme ID

Automate Carefully

• shopify theme push --live — require confirmation or block entirely via CLAUDE.md
• shopify theme delete — same rules
• Anything that modifies the published theme directly

Add a guardrail in your CLAUDE.md:

Never run shopify theme push --live or shopify theme delete without explicit confirmation in the current message. If in doubt, push to an unpublished duplicate and ask me to review.

For broader deployment safety patterns, our guide on customizing Shopify themes without breaking design covers the non-AI workflow you're augmenting.

Common Mistakes to Avoid

Even with a solid setup, a few patterns consistently burn theme devs using Claude Code. Avoid these and you'll save a weekend.

The Meta-Mistake: Skipping the Review

The biggest trap is trusting the diff because the prompt was specific. Always skim the diff before accepting. Look for: schema validity, translation coverage, performance patterns (no DB calls in loops), and preserved block types. Fifteen seconds of review catches 90% of problems. Talk Shop's theme design category has more reading on safe refactor patterns if you want deeper coverage.

Wrap-Up and What's Coming Next

Claude Code plus the Shopify AI Toolkit already handles the boring 70% of Liquid work. Coming faster than most devs expect: agent-driven storefront QA, schema-aware section generators that read Figma files, and integration with Shopify's admin GraphQL for end-to-end changes. The Weaverse breakdown of the Shopify AI toolkit has a useful forward-looking take on the MCP direction.

None of this replaces a senior theme dev who understands Liquid, JSON schemas, and merchant workflows. It replaces the mechanical parts — renaming, porting, linting, translating, scaffolding. Build two or three subagents and you'll compress a week of theme work into a day.

Three moves this week: write a CLAUDE.md for your current theme repo, install the Shopify AI Toolkit, and build one subagent (the lint agent is the easiest). Run your next section refactor through that stack. The first time Claude ports three blocks, adds presets, and passes theme check on the first try — that's when this workflow clicks.

The broader strategic view — how Claude Code fits across Shopify dev, not just themes — lives in the pillar guide to Claude Code for Shopify development. For community discussion and real-world examples from other theme devs, join the Talk Shop community or browse the Shopify experts network for hired specialists.

What's the first Liquid refactor you'd trust an agent with — a section port, a metafield rollout, or a full Dawn customization? The answer says a lot about where your theme debt actually lives.

About Talk Shop

The Talk Shop team — insights from our community of Shopify developers, merchants, and experts.