
Shopify Storefront Graphql
Build and query Shopify Storefront GraphQL from your agent with version-aware doc search and correct API usage for headless storefronts.
Overview
Shopify Storefront GraphQL is an agent skill for the Build phase that helps implement and document-search Shopify Storefront API GraphQL for headless ecommerce.
Install
npx skills add https://github.com/shopify/shopify-ai-toolkit --skill shopify-storefront-graphqlWhat is this skill?
- Targets Shopify Storefront GraphQL for customer-facing commerce APIs
- Tooling resolves shopify.dev docs against multiple supported API versions including unstable and dated releases
- Includes staging-aware base URL resolution via SHOPIFY_DEV_STAGING_SERVER_NUMBER and Minerva token flow
- search_docs-style workflow for agents implementing queries and mutations correctly
- Fits headless storefront, custom checkout, and mobile app commerce stacks
- Defines 6 supported Storefront API version labels in toolkit defaults (unstable plus dated releases)
Adoption & trust: 5.4k installs on skills.sh; 373 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are building a custom storefront but keep hitting wrong GraphQL fields, version mismatches, or outdated Shopify dev docs.
Who is it for?
Indie builders creating headless Shopify storefronts, custom apps, or mobile clients against the Storefront API.
Skip if: Merchants who only customize Online Store 2.0 themes in Liquid without Storefront API code, or Admin API-only internal tools.
When should I use this skill?
Implementing or debugging Shopify Storefront GraphQL queries and mutations, or searching official Shopify dev documentation for Storefront API fields and versions.
What do I get? / Deliverables
Your agent queries current Storefront GraphQL documentation and implements version-aligned operations for your headless shop.
- Version-aligned Storefront GraphQL operations and client integration notes
- Doc-backed answers tied to shopify.dev Storefront schema
Recommended Skills
Journey fit
Headless commerce integration belongs on Build because solo builders adopt it while wiring catalog, cart, and checkout experiences to Shopify's Storefront API. Integrations captures external API contracts, GraphQL operations, and toolkit scripts that talk to shopify.dev—not theme Liquid editing alone.
How it compares
Shopify-specific GraphQL integration helper—not a generic GraphQL tutorial or payment-gateway skill.
Common Questions / FAQ
Who is shopify-storefront-graphql for?
Solo developers using AI coding agents to integrate Shopify's Storefront GraphQL into web or mobile commerce apps.
When should I use shopify-storefront-graphql?
During build while implementing product, cart, and checkout GraphQL operations, searching shopify.dev for schema details, or targeting specific Storefront API versions for launch-ready clients.
Is shopify-storefront-graphql safe to install?
Use the Security Audits panel on this Prism page; staging doc search may require MINERVA_TOKEN—treat tokens as secrets and never commit them.
SKILL.md
READMESKILL.md - Shopify Storefront Graphql
#!/usr/bin/env node // <define:__SUPPORTED_VERSIONS__> var define_SUPPORTED_VERSIONS_default = ["unstable", "2026-07", "2026-04", "2026-01", "2025-10", "2025-07"]; // src/agent-skills/scripts/search_docs.ts import { parseArgs } from "util"; // src/http/index.ts var PROD_BASE_URL = "https://shopify.dev/"; var SHOP_DEV_BASE_URL = "https://shopify-dev.shop.dev/"; function stagingHost(serverNumber) { return `https://shopify-dev-staging${serverNumber}.shopifycloud.com/`; } function resolveShopifyDevBaseUrl(options) { const env = options?.env ?? process.env; const stagingRaw = env.SHOPIFY_DEV_STAGING_SERVER_NUMBER?.trim(); if (stagingRaw) { if (!/^\d+$/.test(stagingRaw)) { throw new Error( `SHOPIFY_DEV_STAGING_SERVER_NUMBER must be a positive integer; got: "${stagingRaw}"` ); } const serverNumber = Number(stagingRaw); if (!Number.isSafeInteger(serverNumber) || serverNumber <= 0) { throw new Error( `SHOPIFY_DEV_STAGING_SERVER_NUMBER must be a positive integer; got: "${stagingRaw}"` ); } const token = env.MINERVA_TOKEN; if (!token) { const audience = stagingHost(serverNumber).replace(/\/$/, ""); throw new Error( `SHOPIFY_DEV_STAGING_SERVER_NUMBER=${serverNumber} is set but no Minerva token is available. Staging servers are behind Minerva. Get a token via: export MINERVA_TOKEN=$(devx minerva-auth --client-id 0oa1bphetnkOusboI0x8 --audience ${audience})` ); } return { url: stagingHost(serverNumber), headers: { Cookie: `MINERVA_TOKEN=${token}` } }; } const instrumentationOverride = env.SHOPIFY_DEV_INSTRUMENTATION_URL?.trim(); if (instrumentationOverride && options?.uri?.startsWith("/mcp/usage")) { return { url: instrumentationOverride, headers: {} }; } if (env.DEV && env.DEV !== "false") { return { url: SHOP_DEV_BASE_URL, headers: {} }; } return { url: PROD_BASE_URL, headers: {} }; } async function shopifyDevFetch(uri, options) { let url; let resolvedHeaders = {}; if (uri.startsWith("http://") || uri.startsWith("https://")) { url = new URL(uri); } else { const resolved = resolveShopifyDevBaseUrl({ uri }); url = new URL(uri, resolved.url); resolvedHeaders = resolved.headers; } if (options?.parameters) { Object.entries(options.parameters).forEach(([key, value]) => { url.searchParams.append(key, value); }); } const response = await fetch(url.toString(), { method: options?.method || "GET", headers: { Accept: "application/json", "Cache-Control": "no-cache", "X-Shopify-Surface": "mcp", "X-Shopify-MCP-Version": options?.instrumentation?.packageVersion || "", "X-Shopify-Timestamp": options?.instrumentation?.timestamp || "", ...resolvedHeaders, ...options?.headers }, ...options?.body && { body: options.body } }); if (!response.ok) { let errorBody; try { errorBody = await response.text(); } catch { } throw new Error( errorBody ? `HTTP ${response.status}: ${errorBody}` : `HTTP error! status: ${response.status}` ); } return await response.text(); } // src/data/supported-versions-schema.json var supported_versions_schema_default = { admin: [ { name: "unstable" }, { name: "2026-07", releaseCandidate: true }, { name: "2026-04", latestVersion: true }, { name: "2026-01" }, { name: "2025-10" }, { name: "2025-07" } ], "storefront-graphql": [ { name: "unstable" }, { name: "2026-07", releaseCandidate: true }, { name: "2026-04", latestVersion: true }, { name: "2026-01" }, { name: "2025-10" }, { name: "2025-07" } ], partner: [ { name: "unstable" }, { name: "2026-07", releaseCandidate: true }, { name: "2026-04", lates