.cursorrules git:20260819.0b329ffA

Immutable. This exact content is served forever at /api/v1/blob/a8a2ce30e3895e20.

---
name: shopify-hydrogen-skill
description: "Skills for building, upgrading, and maintaining Shopify Hydrogen storefronts — includes core Hydrogen patterns, Weaverse integration, feature cookbooks, and upgrade guides."
---

# Shopify Hydrogen Skills

Agent skills for working with Shopify Hydrogen storefronts — covering core framework patterns, Weaverse CMS integration, feature cookbooks, and upgrade guides.

## Live Docs

This repo ships scripts for fetching live documentation from authoritative sources:

```bash
# Shopify Hydrogen docs
node scripts/search_shopify_docs.mjs "<query>"

# Weaverse docs
node scripts/search_weaverse_docs.mjs "<query>"
node scripts/get_weaverse_page.mjs "<page-path>"
```

Use these when you need the latest API references, not the offline references.

## Available Skills

| Skill | Description | When to load |
|-------|-------------|--------------|
| [setup-weaverse-project](./skills/setup-weaverse-project/SKILL.md) | Fast new-project onboarding — CLI scaffold, demo-store boot before credentials, Hydrogen-app store linking + `env pull`, GitHub push, Weaverse MCP live-edit setup, full skills-pack install | Starting a brand-new Weaverse Hydrogen storefront |
| [weaverse-hydrogen](./skills/weaverse-hydrogen/SKILL.md) | Weaverse CMS integration — components, context-aware schemas, loaders, theming, Hydrogen fundamentals | Any Hydrogen + Weaverse project work |
| [shopify-hydrogen](./skills/shopify-hydrogen/SKILL.md) | Core Hydrogen APIs — createHydrogenContext, cart, caching, pagination, SEO, CSP | Working with Hydrogen framework APIs |
| [hydrogen-cookbooks](./skills/hydrogen-cookbooks/SKILL.md) | Step-by-step guides for building common Hydrogen features | Building specific features |
| [hydrogen-upgrades](./skills/hydrogen-upgrades/SKILL.md) | Hydrogen version migration guides and upgrade process | Upgrading Hydrogen |
| [theme-update](./skills/theme-update/SKILL.md) | Pilot theme update — detect version, plan changes, preserve customizations, verify build | Updating a customer's Pilot theme to a newer release |
| [cloning-websites-to-weaverse](./skills/cloning-websites-to-weaverse/SKILL.md) | Reference website cloning workflow for Hydrogen + Weaverse | Cloning a site or brand hub into Weaverse |
| [figma-to-weaverse](./skills/figma-to-weaverse/SKILL.md) | Figma design → Weaverse sections via Figma MCP (token mapping, manifest, preview) | Building a storefront from a Figma file |
| [generating-weaverse-project-json](./skills/generating-weaverse-project-json/SKILL.md) | Weaverse project export JSON generation | Building import-ready Weaverse project files |
| [weaverse-content-api](./skills/weaverse-content-api/SKILL.md) | Read/update live Weaverse content over REST — bulk edits, AI pipelines, Shopify upload | Updating a project after it exists |
| [hydrogen-analytics-tracking](./skills/hydrogen-analytics-tracking/SKILL.md) | End-to-end analytics & conversion tracking — GTM, GA4 (browser + Measurement Protocol), Meta Pixel + CAPI, consent mode, CSP, Oxygen full-page cache, and A/B **experiment-exposure** tracking | Wiring analytics, pixels, server-side conversions, or A/B experiment tracking |

## When to Load Which Skill

- **Working on a Hydrogen + Weaverse project** → load `weaverse-hydrogen`
- **Starting a new Weaverse Hydrogen storefront** → load `setup-weaverse-project`
- **Using Hydrogen framework APIs** (cart, caching, SEO, etc.) → load `shopify-hydrogen`
- **Building a specific feature** (bundles, combined listings, 3D models...) → load `hydrogen-cookbooks`
- **Upgrading Hydrogen version** → load `hydrogen-upgrades`
- **Updating a customer's Pilot theme** → load `theme-update`
- **Cloning a reference website into Weaverse** → load `cloning-websites-to-weaverse`
- **Building a storefront from a Figma design** → load `figma-to-weaverse`
- **Generating Weaverse import JSON** → load `generating-weaverse-project-json`
- **Updating live Weaverse content via API / Shopify resource upload** → load `weaverse-content-api`
- **Wiring analytics / pixels / server-side conversions / A/B experiment-exposure tracking** → load `hydrogen-analytics-tracking`

## About Shopify Hydrogen

Hydrogen is Shopify's React-based framework for building custom storefronts. It is built on top of [React Router v7](https://reactrouter.com/) and [Vite](https://vitejs.dev/), and provides first-class support for the Shopify Storefront API.

Key packages:
- `@shopify/hydrogen` — core utilities (cart, SEO, media, analytics, i18n)
- `@shopify/hydrogen-react` — headless React components and hooks