feat: hydrogen skills check for checking if skills are up to date

[fredericoo]

Stacked on #3992. Merge that first; this diff is the commits after edf93705a.

TL;DR: #3992 makes skills resyncable, but nothing fails when someone bumps Hydrogen and forgets to resync. This adds hydrogen skills check, a read-only command that exits non-zero when the synced skills do not match the installed package, so CI can enforce it.

Before

pnpm add @shopify/hydrogen@preview
# ...forget the next line and agents keep following last version's skills, silently
npx @shopify/hydrogen skills sync

After

npx @shopify/hydrogen skills check
# Hydrogen skills are out of date with @shopify/hydrogen 2026.10.0-preview.3 (5 to update, 2 new, 1 removed upstream). Run `npx @shopify/hydrogen skills sync`.
# exit 1

{
  "scripts": {
    "check:skills": "hydrogen skills check",
    "dev": "hydrogen skills check --mode=warn && vite dev"
  }
}

What this changes

• hydrogen skills check (cli/skills.ts checkSkills): runs the same planner skills sync executes, in read-only mode, and throws with a one-line summary when a sync would add, update, or remove anything, when locally modified skills are behind, or when an unmanaged directory collides with a shipped name. A project that never synced fails too; running the command is the opt-in. Exit 0 prints the version it is aligned with. --mode=warn prints the same message and exits 0, for dev scripts that should nag but not block; --mode=error is the default.
• getSkillsSyncStatus() / describeSkillsSyncStatus(): the read-only view and its message, split out so the CLI cannot disagree with what sync would do. Counts distinct skills rather than directories, since both .claude/skills and .agents/skills are written.
• syncSkills takes force: boolean instead of raw argv; cli/index.ts parses flags once at the boundary.
• hydrogen skills check --mode=warn && <dev> is the standard dev script. Both templates ship it, and the hydrogen-setup skill (scaffold step) instructs agents to prefix the app's existing dev command with it and verifies the chain in the final step. Warn mode prints nothing when skills are current, so the only output is the resync nudge after an upgrade.
• Verified against the release path: prepare:preview-dist syncs skills into both harness roots, and the compiled template's dev prefix is silent afterwards.

Developer impact

Includes a minor changeset for @shopify/hydrogen: one new CLI subcommand under the existing skills namespace. setup and skills sync behaviour is unchanged. No new package exports.

Template source in this monorepo has no skills (they are synced only when compiling dist-preview), so running pnpm dev inside templates/* here prints the "19 new" nudge every time. Compiled templates are silent. Run pnpm exec hydrogen skills sync inside a template to quiet it locally; the generated .claude/skills and .agents/skills are untracked.

Out of scope

• No hydrogen update command and no Vite dev-server warning. Both were built and dropped in review: a top-level command is a permanent compatibility surface for something package managers already do, and there is no umbrella Hydrogen Vite plugin to hang a warning on. skills check in CI is the single gate.
• The hydrogen-setup skill does not yet tell agents to add skills check to a consumer's CI. Deliberate for now.

How to Test

1. Run pnpm install && pnpm build:pkgs.
2. In a scratch directory: mkdir app && cd app && echo '{"name":"app","dependencies":{"@shopify/hydrogen":"*"}}' > package.json.
3. Run node <repo>/packages/hydrogen/bin/hydrogen.mjs skills check. Confirm it reports 19 new skills and exits 1.
4. Run node <repo>/packages/hydrogen/bin/hydrogen.mjs skills sync, then skills check again. Confirm it reports up to date and exits 0.
5. Edit version: in both .agents/skills/hydrogen-money/SKILL.md and .claude/skills/hydrogen-money/SKILL.md to an older version. Run skills check. Confirm it reports 1 to update and exits 1, and that no files changed.
6. Append a line to both hydrogen-money/SKILL.md copies instead. Run skills check. Confirm it reports 1 locally modified and points at --force.
7. Run skills check --mode=warn && echo continued. Confirm the message prints and continued follows. Run skills check --mode=loud and confirm it rejects the value.
8. From the repo root run node scripts/preview-template-dist.ts prepare 2026.10.0-preview.2, then cd templates/react-router && pnpm exec hydrogen skills check --mode=warn. Confirm it prints nothing and exits 0. Restore with git restore templates and remove the generated .agents/.claude dirs.

[fredericoo]

optional, but good practice to keep them in check! this will always warn in local dev as expected, but when in dist-preview it'll work