fix(docs): correct post-CLI-release action guidance in CLAUDE.md

.claude/commands/shopify-cli-update.md

@@ -359,7 +359,9 @@ skeleton template's devDependencies
 @shopify/cli-hydrogen (circular!)
 ```
 
-This may require a second cli-hydrogen release after the Shopify CLI is updated to bundle the correct skeleton version.
+Whether a second cli-hydrogen release is required depends on what the cli-hydrogen changes contained:
+- **If cli-hydrogen had actual code changes** (beyond just adding a changeset to bundle a new skeleton): manually update skeleton's `@shopify/cli` to the new Shopify CLI version and create changesets for `@shopify/cli-hydrogen` AND `@shopify/create-hydrogen` to trigger another release cycle
+- **If cli-hydrogen changes were ONLY a changeset to re-bundle the skeleton**: no further action required after Shopify CLI releases
 
 ## Exit Conditions
 

CLAUDE.md

@@ -100,8 +100,8 @@ Hydrogen uses a sophisticated automated release system built on Changesets, GitH
 
 1. **Developer Actions**
    - **Create changesets**: Run `npm run changeset add` for any PR with code changes
-   - **Skeleton changes**: MUST include `@shopify/cli-hydrogen` in the changeset
-     - This ensures the CLI bundles the latest skeleton template
+   - **Skeleton changes**: MUST include all three packages in changeset: `skeleton`, `@shopify/cli-hydrogen`, AND `@shopify/create-hydrogen`
+     - See [Quick Reference: Contributing to Skeleton or CLI](#quick-reference-contributing-to-skeleton-or-cli) for details
      - Without this, new projects will scaffold with outdated templates
    - **Write PR descriptions**: Include clear explanations of changes
    - **Request snapshot builds**: Comment `/snapit` on PR to test changes
@@ -113,8 +113,7 @@ Hydrogen uses a sophisticated automated release system built on Changesets, GitH
 
 3. **Maintainer Actions - CLI Releases**
    - When cli-hydrogen has updates, create a PR in the Shopify CLI repo and coordinate with Shopify CLI team to request patch release
-   - **Update skeleton after CLI release**: Once @shopify/cli releases, update skeleton's package.json
-   - **Second cli-hydrogen release**: Often required to bundle the updated skeleton
+   - **Post-release actions**: Whether to update skeleton's `@shopify/cli` and trigger a second cli-hydrogen release depends on the nature of the cli-hydrogen changes — see **Skeleton's CLI Version (Post-Release Action)** under *Understanding the Circular Dependency* below
 
 4. **Maintainer Actions - Major Version Changes**
    - **Update latestBranch**: Edit `.github/workflows/changesets.yml` line 32 when moving to new major version
@@ -208,37 +207,104 @@ The skeleton template is the default starter template for new Hydrogen projects:
 
 When developers run `npm create @shopify/hydrogen@latest`:
 
-1. **Package Resolution**
-   - npm resolves `@shopify/create-hydrogen` package
-   - This package calls the `hydrogen init` command from `@shopify/cli-hydrogen`
+1. **Default behavior**: Uses the skeleton template bundled inside `@shopify/create-hydrogen`
+   - No network fetch required—the template is pre-bundled at build time
+   - This is why `create-hydrogen` must be bumped when skeleton changes
 
-2. **Template Fetching**
-   - Downloads the latest Hydrogen release tarball from GitHub
-   - Uses GitHub API: `https://api.github.com/repos/shopify/hydrogen/releases/latest`
-   - Extracts the skeleton template from the tarball
-   - Falls back to local template if running within Hydrogen monorepo
+2. **Custom templates** (`--template` flag): Downloads from GitHub
+   - Uses GitHub API to fetch the specified template
+   - Supports community templates and alternative starters
 
-3. **Template Compilation** (during release)
-   - On production releases, templates are compiled to the `dist` branch
-   - Creates both TypeScript (`skeleton-ts`) and JavaScript (`skeleton-js`) versions
-   - The `dist` branch serves as a stable source for templates
+<details>
+<summary>Technical Details: The Bundling Chain</summary>
 
-### Critical: Skeleton Changes Require CLI Updates
+During a Hydrogen release, templates are bundled through this chain:
 
-**When modifying the skeleton template, you MUST**:
-1. Create a changeset that includes BOTH:
-   - The skeleton template changes
-   - A version bump for `@shopify/cli-hydrogen`
-2. This ensures the CLI contains a snapshot of the latest skeleton in its `dist/assets/templates` directory
-3. Without this, newly scaffolded projects will use an outdated skeleton template
+```
+templates/skeleton/
+    ↓ bundled into
+@shopify/cli-hydrogen (dist/assets/templates/)
+    ↓ bundled into
+@shopify/create-hydrogen (bundles cli-hydrogen at build time)
+    ↓ published to npm
+npm create @shopify/hydrogen@latest
+```
+
+The `dist` branch also receives compiled templates for alternative distribution methods.
+
+</details>
+
+### Quick Reference: Contributing to Skeleton or CLI
+
+#### I'm Updating the Skeleton Template
+
+**Required changeset packages:**
+- `skeleton` — the source you changed
+- `@shopify/cli-hydrogen` — bundles skeleton into its dist
+- `@shopify/create-hydrogen` — bundles cli-hydrogen into its dist
+
+⚠️ **Important**: When you run `npm run changeset add`, it only shows packages with
+actual code changes. You must **manually select** cli-hydrogen and create-hydrogen
+even though you didn't change their code. Alternatively, manually add those lines
+to the changeset file after creation.
+
+**Example changeset:**
+```md
+---
+"skeleton": patch
+"@shopify/cli-hydrogen": patch
+"@shopify/create-hydrogen": patch
+---
+
+Update skeleton template with [description of your changes]
+```
+
+**Canonical example**: See [PR #3232](https://github.com/Shopify/hydrogen/pull/3232) for a complete skeleton update with proper changeset.
+
+<details>
+<summary>Why all three packages?</summary>
+
+The skeleton template is bundled through a chain:
+1. `skeleton` → source code lives in `templates/skeleton/`
+2. `@shopify/cli-hydrogen` → copies skeleton to `dist/assets/templates/` during build
+3. `@shopify/create-hydrogen` → bundles cli-hydrogen (and its templates) at build time
 
-**Why this matters**: The `@shopify/cli-hydrogen` package bundles the skeleton template. If you don't bump its version when changing the skeleton, the CLI will continue distributing the old template version.
+If you only bump `skeleton`, the npm packages won't rebuild with your changes.
+If you only bump `cli-hydrogen`, the `create-hydrogen` package won't include the updated CLI.
+All three must be bumped to ensure `npm create @shopify/hydrogen@latest` gets your changes.
 
-### CLI Release Coordination (Circular Dependency)
+</details>
 
-The CLI system has an inherent circular dependency that requires careful coordination:
+#### I'm Updating the CLI (cli-hydrogen)
+
+**Scenario A: CLI-only change (no init/scaffolding impact)**
+- Just bump `@shopify/cli-hydrogen`
+- Examples: bug fixes in non-init commands such as `dev`, `build`, or `check`; new flags for existing commands
+
+**Scenario B: Change affects the `init` command, scaffolding process, or CLI assets**
+- Bump both `@shopify/cli-hydrogen` and `@shopify/create-hydrogen`
+- Examples: changes to how `hydrogen init` (which powers `npm create @shopify/hydrogen`) works; changes to virtual-route templates or other files in `packages/cli/assets/`
+
+<details>
+<summary>When does a CLI change affect scaffolding?</summary>
+
+`create-hydrogen` bundles two things from `@shopify/cli-hydrogen`:
+1. **The `init` command code** — tree-shaken from the `init` entry point and its transitive dependencies only
+2. **The full `dist/assets` directory** — templates, virtual routes, tailwind configs, and other shared assets
+
+**"Does this change affect the `init` command, or any files in `packages/cli/assets/`?"**
+
+- **Yes** → bump both `cli-hydrogen` and `create-hydrogen`
+- **No** → just bump `cli-hydrogen`
+
+For non-init command changes (bug fixes to commands such as `dev`/`build`/`check`, new non-init commands): these reach newly scaffolded projects through the skeleton's `@shopify/cli` version. If those changes need to be in new scaffolds quickly, follow the circular dependency release cycle described in **Skeleton's CLI Version (Post-Release Action)** under *Understanding the Circular Dependency* below.
+
+</details>
+
+### Understanding the Circular Dependency
+
+The CLI system has an inherent circular dependency, but it's manageable:
 
-**The Circular Dependency Problem**:
 ```
 @shopify/cli-hydrogen (bundles skeleton)
     ↓ is included in
@@ -249,26 +315,24 @@ skeleton template's devDependencies
 @shopify/cli-hydrogen (circular!)
 ```
 
-**Release Process to Handle This**:
+**The circular dependency exists but is manageable:**
 
-1. **First Release**:
-   - Release `@shopify/cli-hydrogen` with new features/fixes
-   - Trigger `@shopify/cli` release to include updated `cli-hydrogen`
-   - Problem: The skeleton bundled in `cli-hydrogen` still references the OLD `@shopify/cli` version
+We break the cycle with a simple rule: skeleton changes → bump all three packages (skeleton, cli-hydrogen, create-hydrogen). This ensures the release includes everything needed.
 
-2. **Second Release Required**:
-   - Update skeleton's `package.json` to use new `@shopify/cli` version
-   - Create another changeset bumping `@shopify/cli-hydrogen`
-   - Release again so future `cli-hydrogen` bundles the updated skeleton
+**Skeleton's CLI Version (Post-Release Action):**
 
-**Example Timeline**:
-- Day 1: Release `@shopify/cli-hydrogen@8.1.0` with new command
-- Day 2: `@shopify/cli@3.80.0` released with updated hydrogen plugin
-- Day 3: Update skeleton to use `@shopify/cli@~3.80.0`
-- Day 4: Release `@shopify/cli-hydrogen@8.1.1` with updated skeleton
-- Result: New projects now have access to the new command
-
-**Key Takeaways**:
-- This process often requires TWO cli-hydrogen releases for complete updates
-- The circular dependency makes the process complex but is currently unavoidable
-- Always check that skeleton's CLI version matches the features available in cli-hydrogen
+After Shopify CLI releases a new version containing updated `@shopify/cli-hydrogen`, whether further action is required depends on what the cli-hydrogen changes contained:
+
+**If cli-hydrogen had actual changes** (any code changes: bug fixes, new commands, refactors — anything beyond just adding a changeset to bundle a new skeleton template):
+- Manually update skeleton's `@shopify/cli` dependency to the new Shopify CLI version
+- Create changesets for `@shopify/cli-hydrogen` AND `@shopify/create-hydrogen`
+- This triggers another cli-hydrogen release (now bundling the updated skeleton) and another Shopify CLI release
+- Required so new Hydrogen storefronts are created with the latest cli-hydrogen changes
+
+**If cli-hydrogen changes were ONLY a changeset to re-bundle the skeleton** (no actual code changes to cli-hydrogen itself):
+- No further action required after Shopify CLI releases
+- The skeleton's `@shopify/cli` version does not need to be updated
+
+**The key question**: "Were there actual code changes to cli-hydrogen, beyond just adding a changeset to bundle an updated skeleton?"
+- **Yes** → Manually update skeleton's CLI version and release another cli-hydrogen cycle
+- **No** → Done