shopify-hydrogen-skills
Dedicated agent skills for building, upgrading, and maintaining Shopify Hydrogen storefronts — works with Claude, Cursor, Copilot, and more.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/weaverse--shopify-hydrogen-skills)HTML
<a href="/listings/weaverse--shopify-hydrogen-skills"><img src="/api/listings/weaverse--shopify-hydrogen-skills/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Claude Code: Skills and Store Connection
Run this in your terminal with [Claude Code 2.1.292 or later](https://code.claude.com/docs/en/plugins/install#add-and-install-from-your-shell):
claude plugin install weaverse --marketplace Weaverse/shopify-hydrogen-skills
This adds our repository-hosted marketplace and installs the `weaverse` plugin for your Claude Code user. The plugin includes every skill in `skills/` and registers the hosted `weaverse` MCP server at `https://mcp.weaverse.io/mcp`. No Content API key is needed.
Start a new Claude Code session, open `/mcp`, and authenticate the Weaverse server. Sign in with your Shopify store and review the requested access; leave optional permissions unchecked for read-only use. Ask the agent to call `list_projects` to check which store it can see. Plugin skills use names such as `/weaverse:setup-weaverse-project`.
Update with `claude plugin update weaverse@weaverse`; auto-update is off by default for third-party marketplaces. Enable it in `/plugin` → **Marketplaces** → **weaverse** → **Enable auto-update** ([guide](https://code.claude.com/docs/en/plugins/install#keep-plugins-updated)).
Already installed the skills with `npx skills add`? Keep them and add just the store connection instead:
claude mcp add --transport http weaverse https://mcp.weaverse.io/mcp
Codex, Cursor, and Other Agents
The skills-only installation is unchanged:
npx skills add Weaverse/shopify-hydrogen-skills
Select your agent and installation scope when prompted. Powered by [skills.sh](https://skills.sh).
For store access, Codex, Cursor, and other MCP clients use the local `npx -y @weaverse/mcp` server with `WEAVERSE_API_KEY`. Create a Content API key in [Dashboard → Account → API Keys](https://studio.weaverse.io/dashboard/account), then follow the [per-agent connection steps](https://docs.weaverse.io/developer-tools/weaverse-mcp#client-configuration). Keep keys private and out of version control.
Review or disconnect hosted access in [Dashboard → Account → Connected AI apps](https://studio.weaverse.io/dashboard/account). Revoke local-server API keys under **API Keys** on the same page. For older Claude Code versions and manual per-agent setup, see [INSTALL.md](INSTALL.md).
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 14 lines
- {
- "name": "weaverse",
- "owner": {
- "name": "Weaverse",
- "url": "https://weaverse.io"
- },
- "description": "Skills and store connection for Shopify Hydrogen development with Weaverse.",
- "plugins": [
- {
- "name": "weaverse",
- "source": "./"
- }
- ]
- }
README.md · README · 203 lines
- # Shopify Hydrogen Skills
- Agent skills for building, maintaining, and upgrading Shopify Hydrogen storefronts with [Weaverse](https://weaverse.io). Works with **Claude Code, Cursor, GitHub Copilot, Windsurf, OpenCode, OpenClaw, Gemini CLI**, and any agent that supports markdown skill files.
- > **Why skills, not docs?** Skills are concise, agent-optimized knowledge that your coding agent loads before working on a task — structured for LLMs, not humans. Pair them with live doc search for the best results.
- > **Versions.** The skills target **Hydrogen 2026.10** (`@shopify/hydrogen` as a request-handler library), React Router 7 and **`@weaverse/hydrogen` 6** (imports from `@weaverse/hydrogen/react-router`), with [Pilot](https://github.com/Weaverse/pilot) `main` as the reference implementation. Classic Hydrogen (2026.4 and earlier) and `@weaverse/hydrogen` 5 appear only in the upgrade and migration guides.
- ## Quick Install
- ### Claude Code: Skills and Store Connection
- Run this in your terminal with [Claude Code 2.1.292 or later](https://code.claude.com/docs/en/plugins/install#add-and-install-from-your-shell):
- ```bash
- claude plugin install weaverse --marketplace Weaverse/shopify-hydrogen-skills
- ```
- This adds our repository-hosted marketplace and installs the `weaverse` plugin
- for your Claude Code user. The plugin includes every skill in `skills/` and
- registers the hosted `weaverse` MCP server at `https://mcp.weaverse.io/mcp`.
- No Content API key is needed.
- Start a new Claude Code session, open `/mcp`, and authenticate the Weaverse
- server. Sign in with your Shopify store and review the requested access; leave
- optional permissions unchecked for read-only use. Ask the agent to call
- `list_projects` to check which store it can see. Plugin skills use names such as
- `/weaverse:setup-weaverse-project`.
- Update with `claude plugin update weaverse@weaverse`; auto-update is off by default
- for third-party marketplaces. Enable it in `/plugin` → **Marketplaces** →
- **weaverse** → **Enable auto-update** ([guide](https://code.claude.com/docs/en/plugins/install#keep-plugins-updated)).
- Already installed the skills with `npx skills add`? Keep them and add just the
- store connection instead:
- ```bash
- claude mcp add --transport http weaverse https://mcp.weaverse.io/mcp
- ```
- ### Codex, Cursor, and Other Agents
- The skills-only installation is unchanged:
- ```bash
- npx skills add Weaverse/shopify-hydrogen-skills
- ```
- Select your agent and installation scope when prompted. Powered by [skills.sh](https://skills.sh).
- For store access, Codex, Cursor, and other MCP clients use the local
- `npx -y @weaverse/mcp` server with `WEAVERSE_API_KEY`. Create a Content API key
- in [Dashboard → Account → API Keys](https://studio.weaverse.io/dashboard/account),
- then follow the [per-agent connection steps](https://docs.weaverse.io/developer-tools/weaverse-mcp#client-configuration).
- Keep keys private and out of version control.
- Review or disconnect hosted access in
- [Dashboard → Account → Connected AI apps](https://studio.weaverse.io/dashboard/account).
- Revoke local-server API keys under **API Keys** on the same page.
- For older Claude Code versions and manual per-agent setup, see [INSTALL.md](INSTALL.md).
- ---
- ## Skills
- | Skill | What the agent learns | When to load |
- |-------|----------------------|--------------|
- | [`setup-weaverse-project`](./skills/setup-weaverse-project/SKILL.md) | Fast new-project onboarding — CLI-first scaffold, demo-store boot before credentials, generated `SESSION_SECRET`, GitHub repo, Builder preview connection | Starting a brand-new Weaverse Hydrogen storefront or running a theme locally for the first time |
- | [`shopify-hydrogen`](./skills/shopify-hydrogen/SKILL.md) | Core Hydrogen 2026.10 APIs — `server.ts` request lifecycle, `handleShopifyRoutes`, `storefront.graphql(gql())` with explicit cache, cart store, Customer Account handlers | Working with `@shopify/hydrogen` APIs |
- | [`weaverse-hydrogen`](./skills/weaverse-hydrogen/SKILL.md) | Weaverse components, schemas, loaders, theming, deployment | Any Hydrogen + Weaverse project |
- | [`hydrogen-cookbooks`](./skills/hydrogen-cookbooks/SKILL.md) | Step-by-step guides — bundles, combined listings, 3D models, customer accounts, performance | Building specific features |
- | [`hydrogen-upgrades`](./skills/hydrogen-upgrades/SKILL.md) | Breaking changes and migration steps for Hydrogen framework versions | Upgrading Hydrogen framework |
- | [`theme-update`](./skills/theme-update/SKILL.md) | Safe Pilot theme updates — detect version, plan changes, preserve customizations, verify build | Updating a customer's Pilot theme |
- | [`weaverse-integration`](./skills/weaverse-integration/SKILL.md) | Integrate Weaverse into an existing Hydrogen project — analyze codebase, convert components, set up SDK, configure routes | Adding Weaverse to a project that doesn't use it yet |
- | [`cloning-websites-to-weaverse`](./skills/cloning-websites-to-weaverse/SKILL.md) | Recreate reference websites as Hydrogen + Weaverse pages with preview checkpoints and section mapping | Cloning a site or brand hub into Weaverse |
- | [`figma-to-weaverse`](./skills/figma-to-weaverse/SKILL.md) | Turn a Figma design into Weaverse sections via Figma MCP — token mapping, component-state-driven interactions, content manifest, preview checkpoint, Playwright visual + hover/click check against Figma until PASS | Building a storefront from a Figma file |
- | [`generating-weaverse-project-json`](./skills/generating-weaverse-project-json/SKILL.md) | Generate import-ready Weaverse project export JSON from section plans, specs, or existing exports | Building Weaverse import files |
- | [`weaverse-content-api`](./skills/weaverse-content-api/SKILL.md) | Read/update Weaverse content over the REST Content API — live item edits, drafts and explicit publish/schedule/restore, translations, project lifecycle, Shopify resource upload | Updating a project's content, publishing flow, or translations via API |
- | [`hydrogen-analytics-tracking`](./skills/hydrogen-analytics-tracking/SKILL.md) | End-to-end tracking on Hydrogen — GTM, GA4 (browser + Measurement Protocol), Meta Pixel + CAPI, Google Ads, Consent Mode v2, CSP, Oxygen FPC, Weaverse webhook forwarding | Implementing analytics/conversion tracking on a Hydrogen storefront |
- | [`hydrogen-markets-localization`](./skills/hydrogen-markets-localization/SKILL.md) | End-to-end Shopify Markets localization — canonical market config, locale routing, Weaverse translations, RTL, cart/account/checkout continuity, SEO, and production readback | Adding or reviewing markets, locales, translations, hreflang, or localized commerce flows |
- ### Weaverse build pipeline
- The site-building skills chain from a source (website or Figma) to a live, maintainable Weaverse project:
- ```
- INPUT ADAPTERS GENERATE DELIVER
- cloning-websites-to-weaverse ┐
- ├─→ generating-weaverse-project-json ─→ import once into Studio (creates structure)
- figma-to-weaverse ┘ └─→ weaverse-content-api (updates content after,
- bulk edits, Shopify resource upload)
- ```
- Initial structure is created by importing the generated JSON, page-by-page via `POST /projects/:projectId/pages`, or as a whole project via the Content API's project lifecycle. Everything after — copy, images, localization, bulk edits, staged draft→publish flows — goes through the Content API, which updates existing items, adds new typed items, relinks children, creates/deletes pages, and restores versions.
- ---
- ## Live Docs
- Instead of baking static API docs into skill files (which go stale), this repo ships **live doc fetching scripts** that query official sources at runtime:
- ```bash
- # Search Shopify Hydrogen docs (shopify.dev)
- node skills/shopify-hydrogen/scripts/search_shopify_docs.mjs "handleShopifyRoutes"
- node skills/shopify-hydrogen/scripts/search_shopify_docs.mjs "createCartServerHandlers"
- # Search Weaverse docs (docs.weaverse.io)
- node skills/shopify-hydrogen/scripts/search_weaverse_docs.mjs "component schema"
- # Fetch a specific Weaverse doc page
- node skills/shopify-hydrogen/scripts/get_weaverse_page.mjs "development-guide/component-schema"
- # Check for Pilot theme updates
- node skills/theme-update/scripts/check_pilot_updates.mjs
- ```
- The `references/` folders in each skill serve as **offline fallback** — cached snapshots for when live search is unavailable.
- | Script | Source | Endpoint |
- |--------|--------|----------|
- | `shopify-hydrogen/scripts/search_shopify_docs.mjs` | shopify.dev | Hydrogen API search |
- | `shopify-hydrogen/scripts/search_weaverse_docs.mjs` | weaverse.io/docs | Weaverse docs search (Mintlify MCP) |
- | `shopify-hydrogen/scripts/get_weaverse_page.mjs` | weaverse.io/docs | Full page fetch by path |
- | `shopify-hydrogen/scripts/check_docs_helpers.mjs` | none | Helper boundary checks (offline) |
- | `theme-update/scripts/check_pilot_updates.mjs` | github.com | Pilot release version check |
- All scripts are **zero-dependency** — Node.js 18+ built-ins only.
- ---
- ## Repo Structure
- ```
- ├── skills/
- │ ├── setup-weaverse-project/ # New project setup from zero to local preview
- │ │ └── SKILL.md
- │ │
- │ ├── shopify-hydrogen/ # Core Hydrogen APIs
- │ │ ├── SKILL.md
- │ │ └── references/ # Setup, caching, cart patterns
- │ │
- │ ├── weaverse-hydrogen/ # Weaverse CMS integration
- │ │ ├── SKILL.md
- │ │ ├── references/ # 15 deep-dive guides
- │ │ └── examples/ # Production-ready component code
- │ │
- │ ├── hydrogen-cookbooks/ # Feature recipes
- │ │ ├── SKILL.md
- │ │ └── references/ # Bundles, combined listings, 3D, etc.
- │ │
- │ ├── hydrogen-upgrades/ # Framework version migrations
- │ │ ├── SKILL.md
- │ │ └── references/ # 2024.4.7 → … → 2026.10.2
- │ │
- │ ├── theme-update/ # Pilot theme updater
- │ ├── SKILL.md
- │ └── scripts/
- │ └── check_pilot_updates.mjs
- │
- │ ├── weaverse-integration/ # Integrate into existing Hydrogen
- │ └── SKILL.md
- │
- │ ├── cloning-websites-to-weaverse/ # Clone sites into Weaverse
- │ │ └── SKILL.md
- │
- │ ├── figma-to-weaverse/ # Figma design → Weaverse sections
- │ │ ├── SKILL.md
- │ │ └── references/ # Figma MCP extraction + token mapping
- │
- │ ├── generating-weaverse-project-json/ # Weaverse import JSON generator
- │ │ ├── SKILL.md
- │ │ ├── references/
- │ │ └── scripts/
- │
- │ ├── weaverse-content-api/ # Live content read/update over REST
- │ │ ├── SKILL.md
- │ │ ├── references/ # Endpoints + Portable Text
- │ │ └── scripts/
- │ │ └── weaverse_content_api.mjs
- │ │
- │ └── hydrogen-markets-localization/ # Markets and localization workflow
- │ ├── SKILL.md
- │ └── references/ # Verification checklist
- │
- ├── .cursorrules # Cursor agent rules
- ├── AGENTS.md # Repo guidance for AI agents
- ├── INSTALL.md # Manual per-agent install guide
- └── package.json
- ```
- ---
- ## Contributing
- PRs welcome — especially for:
- - New cookbooks (feature implementation guides)
- - Upgrade guides for newer Hydrogen versions
- - Improved offline references
- - New live doc scripts for other sources
- ## License
- MIT — [Weaverse](https://weaverse.io)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.