Skip to main content

​
Shopify Hydrogen Skills

Agent skills for building, maintaining, and upgrading Shopify Hydrogen storefronts with Weaverse. 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 Weaverse MCP for live doc search and the best results.

​
Quick Install

npx skills add Weaverse/shopify-hydrogen-skills
Auto-detects your coding agents and installs to all of them. Powered by skills.sh. For manual per-agent setup, see the INSTALL.md.

​
Available Skills

shopify-hydrogen

Core Hydrogen APIs — createHydrogenContext, cart handler, caching, pagination, SEO, CSP. Load when working with @shopify/hydrogen APIs.

weaverse-hydrogen

Weaverse components, schemas, loaders, theming, deployment. Load for any Hydrogen + Weaverse project.

hydrogen-cookbooks

Step-by-step guides — bundles, combined listings, 3D models, customer accounts, performance. Load when building specific features.

hydrogen-upgrades

Breaking changes and migration steps for Hydrogen framework versions. Load when upgrading Hydrogen.

theme-update

Safe Pilot theme updates — detect version, plan changes, preserve customizations, verify build. Load when updating a customer’s Pilot theme.

weaverse-integration

Integrate Weaverse into an existing Hydrogen project — analyze codebase, convert components, set up SDK, configure routes. Load when adding Weaverse to a project that doesn’t use it yet.

​
Live Doc Fetching

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: 
# Search Shopify Hydrogen docs (shopify.dev)
node scripts/search_shopify_docs.mjs "createHydrogenContext"
node scripts/search_shopify_docs.mjs "CartForm actions"

# Search Weaverse docs (docs.weaverse.io)
node scripts/search_weaverse_docs.mjs "component schema"

# Fetch a specific Weaverse doc page
node scripts/get_weaverse_page.mjs "development-guide/component-schema"

# Check for Pilot theme updates
node skills/theme-update/scripts/check_pilot_updates.mjs
ScriptSourceWhat it does
search_shopify_docs.mjsshopify.devSearch Hydrogen API docs
search_weaverse_docs.mjsdocs.weaverse.ioSearch Weaverse docs via Mintlify MCP
get_weaverse_page.mjsdocs.weaverse.ioFetch full page content by path
check_pilot_updates.mjsgithub.comCheck for Pilot theme release updates
All scripts are zero-dependency — Node.js 18+ built-ins only. The references/ folders in each skill serve as offline fallback — cached snapshots for when live search is unavailable.

​
Repo Structure

├── skills/
│   ├── shopify-hydrogen/          # Core Hydrogen APIs
│   │   ├── SKILL.md
│   │   └── references/            # Setup, caching, cart patterns
│   ├── weaverse-hydrogen/         # Weaverse CMS integration
│   │   ├── references/            # 13 deep-dive guides
│   │   └── examples/              # Production-ready component code
│   ├── hydrogen-cookbooks/        # Feature recipes
│   │   └── references/            # Bundles, combined listings, 3D, etc.
│   ├── hydrogen-upgrades/         # Framework version migrations
│   │   └── references/            # Version-specific migration guides
│   ├── theme-update/              # Pilot theme updater
│   │   ├── SKILL.md
│   │   └── scripts/
│   └── weaverse-integration/      # Integrate into existing Hydrogen
│       └── SKILL.md
├── scripts/                       # Live doc fetching (shared)
├── .cursorrules                   # Cursor agent rules
├── AGENTS.md                      # Repo guidance for AI agents
└── INSTALL.md                     # Manual per-agent install guide

​
Using with Weaverse MCP

For the best development experience, combine agent skills with Weaverse MCP:
  • Skills provide structured knowledge your agent loads before tasks
  • MCP provides real-time doc search for up-to-date API details
Together, your AI coding agent has both deep context and live access to the latest documentation.

​
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

GitHub Repository

View source, report issues, and contribute on GitHub