Skip to main content

​
AI Theme Workflows

AI works best when it follows the same control-plane loop as a careful developer: 
inspect -> search -> read -> apply -> validate -> preview -> publish

​
Good AI Tasks

Good:
  • “Find the hero section and change only the CTA copy.”
  • “Add a testimonials section using the same spacing as the feature section.”
  • “Fix the Liquid validation error, then preview.”
  • “Update the product card markup but keep platform cart behavior.”
Risky:
  • “Rewrite the whole storefront.”
  • “Change anything you think looks bad.”
  • “Bypass validation.”
  • “Move checkout logic into the theme.”

​
Required Scopes

Use an API key with:
  • themes.read
  • themes.write
An inspect-only assistant can use themes.read alone.

​
CLI Workflow

shoppex auth login --api-key shx_your_key
shoppex theme list
shoppex theme inspect --theme "$THEME_ID"
shoppex theme pull --theme "$THEME_ID" --out ./my-theme
cd ./my-theme
shoppex theme dev
After edits: 
shoppex theme push --preview --include-typecheck
shoppex theme publish

​
Local AI Handoff Workflow

Use this when a human starts work, an AI edits locally, and another human or AI reviews it.
1

Human creates a scoped key

Use only themes.read and themes.write.
2

AI pulls and inspects

The assistant runs theme list, theme pull, theme inspect, then reads only the relevant Liquid files.
3

AI runs local preview

The assistant starts shoppex theme dev and uses fixture data unless the change depends on real catalog, stock, product detail, or settings data.
4

AI makes a narrow change

One section, snippet, CSS area, or settings/schema change at a time.
5

AI validates and previews

The assistant runs shoppex theme validate --include-typecheck and shoppex theme push --preview --include-typecheck.
6

Human reviews publish decision

Publish only after the preview has been reviewed. AI should not publish unless explicitly asked.
Simple example: 
Pull my active Liquid theme, inspect the file tree, find the homepage hero,
change only the CTA label, run validation, push a preview, and hand me the preview URL.
Do not publish.

​
MCP Workflow

Set: 
export SHOPPEX_API_URL=https://api.shoppex.io
export SHOPPEX_API_KEY=shx_your_key
Useful tools:
  • theme.inspect
  • theme.search_files
  • theme.read_file
  • theme.apply
  • theme.create_section
  • theme.create_page
  • theme.update_config
  • theme.validate
  • theme.preview
  • theme.publish

​
Liquid-Specific Prompt Rules

Tell the assistant:
  • Keep templates presentational.
  • Preserve data-builder-block and data-builder-block-type.
  • Use static {% render "snippets/name" %} calls only.
  • Use safe_href for user URLs.
  • Use | raw only for platform-owned HTML.
  • Do not compute stock, price, sorting, or checkout rules in Liquid.
  • If a new file is added, declare it in theme-package.json.
  • Keep platform commerce hooks and data attributes intact.
  • Prefer preview over publish unless the prompt explicitly says publish.
Simple prompt:
Inspect the theme, find the product card snippet, and adjust only the badge layout. Keep the existing platform data attributes and cart behavior. Validate and start a preview.

​
Handoff Block

At the end of a non-trivial AI theme session, ask the assistant to leave this: 
## Scope
Theme id:
Files changed:
User-facing change:

## Verification
shoppex theme validate --include-typecheck:
shoppex theme preview:
Preview URL:
Cart/checkout checked:

## Publish state
Published: yes/no
If yes, publish job id:

## Risks / not verified
-

## Next recommended action
-
This makes the next person or AI agent faster. Simple example: if cart/checkout was not checked because the change only touched homepage copy, say that explicitly.

​
Review Before Publish

Before publishing, check:
  • validation passed
  • preview URL shows the change
  • cart and checkout still work
  • no unsafe Liquid or dynamic partials were added
  • diff matches the intended change

​
Next Steps

Editing Themes

Shared dashboard, CLI, Dev API, and MCP workflow.

Core Contract

Liquid responsibilities and safety rules.