Hydrogen Agent Skills Now Have a Sync Command and a CI Gate

Your storefront package can be current while the instructions your coding agent reads are still from the last upgrade.

Shopify's September 11 release of @shopify/hydrogen@2026.10.0-preview.3 addresses that gap with two commands: hydrogen skills sync updates packaged agent instructions, and hydrogen skills check reports whether a sync is needed without changing files.[1]

Weaverse has also brought Agent Skills into Builder, giving developers a task-based starting point instead of the old deployment-guide entry. The two changes serve different jobs: Shopify manages its package's skills; Weaverse helps you choose and hand off storefront work to your coding agent.

Scope first: Shopify's new commands belong to the Hydrogen developer preview. This is not an instruction to replace the Hydrogen dependency in an existing stable storefront. Shopify still identifies current Hydrogen as its fully supported React Router path.[2]

What changed: skills can follow the installed package

The preview already ships focused instructions for coding agents. The new sync command gives those instructions an update lifecycle rather than leaving teams to manage an old setup-time copy.[1][2]

In the verified 2026.10.0-preview.3 package, syncing creates 19 skills in each of these locations:

.claude/skills, for Claude Code.
.agents/skills, for Codex, Cursor and OpenCode.[1]

Those are two copies of the same 19-skill set, not 38 different skills. We verified the directory sets against the installed package in a disposable local project.

Each synced SKILL.md records its source package, package version and a content hash in frontmatter metadata. The sync planner uses that information to distinguish an untouched copy from local edits and unmanaged files.[4]

This is version alignment, not an automatic fetch of the newest release: the command resolves the @shopify/hydrogen installed for the project and works from that package's skills.[4]

Run sync from the preview project

For a project already using the preview release discussed here, first confirm the installed dependency:

npm ls @shopify/hydrogen

bash

Add these entries to the project's existing package.json scripts. Keep the rest of the file unchanged:

{
  "scripts": {
    "skills:sync": "hydrogen skills sync",
    "skills:check": "hydrogen skills check"
  }
}

json

Then run:

npm run skills:sync
npm run skills:check

bash

Using npm scripts runs the project's installed binary. In our clean scratch project, the check exited with code 1 before any skills were synced. Sync added the skills to both directories, and the next check exited with code 0.

After a preview-package upgrade, sync can update unmodified skills, add newly shipped skills and remove managed skills the package no longer ships. Locally modified skills are preserved unless you explicitly use --force; edited skills removed upstream require a removal decision and are kept with a warning when no interactive terminal is available.[1][4]

Review the resulting diff with the package upgrade. Do not treat generated instructions as files nobody needs to read.

Add a CI check, not a silent CI repair

The default check mode is error. Missing skills or pending synchronization changes produce a non-zero exit. The command reports the problem without writing the skill files.[1][4]

In an existing CI job that has checked out the repository and configured its Node environment, the relevant steps are:

- name: Install locked dependencies
  run: npm ci

- name: Check Hydrogen skill alignment
  run: npm run skills:check

yaml

For this workflow, track the synced .claude/skills and .agents/skills files in Git. Otherwise a clean checkout starts without them and the check correctly fails.

Do not put skills:sync immediately before this check in CI if your goal is to catch stale committed instructions. That would repair the checkout before checking it, masking the difference you wanted the pull request to expose.

For a local development script where you want a warning rather than a blocking exit:

npm run skills:check -- --mode=warn

bash

Warn mode reports the same drift but exits successfully. It is not a blocking CI gate.[1]

What a green check does not prove

skills check is not a blanket ban on local edits. In this release, a modified skill can still pass when its recorded package version and source hash match the current packaged skill. Once that recorded source is stale, the modified copy is reported as drift instead.[4]

We tested both cases against the published package: a same-version local edit passed, while a local edit carrying stale version metadata failed. A normal sync preserved the latter; an explicitly forced sync reset it.

A passing check therefore does not prove that:

Every instruction file is byte-identical to Shopify's copy.
An agent loaded or followed those instructions.
The generated storefront code is correct.
A separate Weaverse skill pack is current or compatible with your application.

Keep code review, type checks and storefront tests. This check covers one narrower failure: the synchronization state of Shopify's packaged skills.

Adopting skills copied by an older setup command

Projects that ran hydrogen setup before this release may have skill copies without the new metadata. Shopify documents a one-time forced sync to adopt those copies.[1]

Commit or back up local skill edits first. With the npm script above, run:

npm run skills:sync -- --force
npm run skills:check

bash

--force can overwrite local changes. It is a deliberate migration or reset option, not something to append permanently to your normal workflow.[1][4]

There is also a legacy cleanup boundary: old, unmanaged skill copies whose names are no longer shipped cannot be recognized as Hydrogen-owned. Shopify says those need manual deletion. Inspect and back them up before removing anything; do not delete unrelated agent skills.[1]

Weaverse Builder: from a deployment guide to Agent Skills

Builder's Resources → Agent Skills page puts the next development task in front of you: install the Weaverse pack, choose an outcome and copy the task prompt into your agent.

Weaverse Builder Agent Skills page with coding-agent installation tabs, a copyable install command, and storefront setup and integration task cards.

The Agent Skills page in Weaverse Builder: an install-once panel followed by task prompts. Screenshot supplied September 14, 2026; browser and account chrome cropped out.

The page offers installation tabs for Claude Code, Codex, Cursor and other agents. Its task catalog includes starting a Weaverse storefront, making an existing storefront editable, building editable sections and building from Figma.[3]

For Claude Code, the command shown is:

npx skills add Weaverse/shopify-hydrogen-skills --skill '*' --agent claude-code

bash

Run it inside the storefront repository and choose Project when asked where to install. If the repository does not exist yet, use the setup prompt first, then install the pack inside the repository it creates. Installing in a parent folder does not automatically make the skills available inside a new nested repository.[3]

Copying the command does not install anything. Copying a task prompt does not run the task. The developer still runs the command and gives the prompt to the coding agent. Installing the pack also does not grant Shopify, Figma or API access; those remain separate prerequisites.[3]

For teams building with Weaverse, this makes the starting point more useful than a deployment-only entry. The task can begin with scaffolding a storefront or making a section editable, not just putting an already-built application online.

Two skill systems, two responsibilities

Do not confuse the Weaverse installation command with Shopify's sync command:

Shopify's packaged skills explain the Hydrogen preview APIs and are synchronized against the project's installed @shopify/hydrogen.[1][4]
Weaverse's skill pack provides Weaverse and Hydrogen storefront workflows from its own repository.[3]

Shopify's skills check is not a freshness check for Weaverse's repository. Nor does installing either pack establish that an existing storefront supports the preview's API changes. Choose instructions that match the stack your project actually uses.

For the broader architecture context, see our explanation of the framework-agnostic Hydrogen preview. This article is about maintaining instructions and choosing tasks, not a storefront migration guide.

The useful next step

If you are already testing the Hydrogen preview, sync the packaged skills locally, review the diff and add a check after dependency installation in CI.

If you are building a Weaverse storefront, open Agent Skills in Builder or inspect the Weaverse skill pack, then choose one concrete task for your agent.

The useful change is not simply having more prompts. It is knowing which package owns an instruction, when that instruction needs updating, and what work you are asking the agent to perform.