shopifyultimate

01 · What it does

The problem it solves

Editing a Shopify theme programmatically fails in quiet ways: settings_data.json validates atomically and silently reverts on a bad font handle, a file upsert returns with no errors while nothing actually changed, and a new product stays invisible because it is draft and unpublished. This is a playbook of those failure modes and the exact call order that avoids them, from production work on Shopify’s Horizon theme. It covers moving file bytes with the CLI or staged uploads, catalogue and collection mutations, branding, and verifying every write by re-fetching instead of trusting the response.

02 · Setup

Before you start

• ✓An authenticated Shopify Admin GraphQL connection or an authenticated Shopify CLI
• ✓A Shopify store, ideally on the Horizon theme
• ✓An agent that loads Agent Skills, such as Claude Code or Cursor
• ✓A browser for live verification — fetching HTML cannot render CSS, fonts or JS

03 · Step by step

Getting it running

1. 01

   Get the skill onto disk

   Clone the repo. It contains one skill with a SKILL.md and twelve reference files.

   $git clone https://github.com/ca-who-codes/shopifyultimate
2. 02

   Copy the skill folder into your agent

   The README’s plugin-marketplace command has no manifest behind it, so copy the folder into .claude/skills/ or .agents/skills/ instead.

   $mkdir -p .claude/skills && cp -R shopifyultimate/skills/shopify-theme-ops .claude/skills/
3. 03

   Confirm your Shopify connection

   The skill assumes auth already works and does not cover setting it up. This command tells you whether the CLI is authenticated, since it prints the store’s themes or prompts you to log in.

   $shopify theme list
4. 04

   Keep a local mirror and pull fresh before editing

   Never edit from a stale copy — the theme editor overwrites settings_data.json behind your back. Pull the specific files you are about to touch.

   $shopify theme pull --only config/settings_data.json --theme <THEME_ID> --path .
5. 05

   Build the new file on disk with a script

   The central rule is to move bytes, not text: never hand-type or paste file contents into a tool call. Generate JSON with a script so everything you did not touch stays byte-identical.

6. 06

   Push only the files you changed

   Without --only, a push syncs the whole theme and deletes remote files missing from your mirror. --nodelete is the belt-and-braces guard.

   $shopify theme push --only templates/index.json --theme <THEME_ID> --nodelete
7. 07

   Re-fetch and diff to prove the write applied

   A clean response is necessary but not sufficient. Request the checksum and size alongside the body, then compare against what you pushed.

8. 08

   Look at the live page in a browser

   Inspect the live DOM to get exact class names before writing any CSS, because Horizon’s classes vary by version.

04 · What you get

Capabilities

05 · Before you rely on it

Limitations, honestly

Every tool has edges. These are the ones that will cost you time if nobody tells you first.

• !The repo has no plugin marketplace manifest, so the README’s install command has nothing to resolve — copy the skill folder in by hand.
• !Authentication is explicitly out of scope; it assumes you already have a working CLI or API connection.
• !Written against the Horizon theme, so the colour model, class names and grid settings largely do not transfer to Dawn or older themes.
• !Selectors are pinned to specific Horizon versions — verify against the live DOM before trusting any of them.
• !This is a prose playbook, not code. No scripts, tests or CI, and nothing verifies the mutations still match Shopify’s current API.
• !One recommended pattern hosts product images in a public repo, which puts store assets on a third-party public host.
• !Both README and SKILL.md declare MIT, but the repo contains no LICENSE file.