Terminal
Terminal/Skill
Helps you build or adapt a Shopify storefront on Vercel Shop patterns, covering routes, commerce data, caching, cart and account.
By Vercel
Works with
npx skills add vercel/shop --skill build-shopBuild the shop around commerce truth first: what product or collection is being shown, what the customer has selected, what can be bought now, what price is authoritative, and what state belongs in the URL, Shopify, the server cache, or the browser. Use Vercel Shop's template as the reference implementation, but adapt the behavior to the current storefront instead of copying files blindly.
AGENTS.md, the target route, its view contract, and every operation it calls.AGENTS.mdapp/layout.tsx, app/page.tsxlib/shopify/storefront/server.ts, lib/shopify/operations/, lib/shopify/transforms/, lib/product/types.ts, lib/customer/types.tslib/<domain>/server.ts cached get* wrappers around the uncached fetch* operationscomponents/ui/container.tsx, components/ui/page.tsx, components/ui/sections.tsxnode_modules/next/dist/docs/ for any API being changed. This template may use newer Cache Components and prefetch behavior than model knowledge.notFound() behavior unless the task explicitly changes the domain behavior.The template uses the framework-agnostic Hydrogen preview SDK, not Hydrogen's React Router application framework. Next.js owns routing, rendering, public-data caching, and invalidation. Hydrogen owns commerce state and protocols; the template supplies presentation and framework adapters. Use Hydrogen's cart provider/forms/handlers rather than rebuilding cart state or hydration. Cart types are handler-derived; catalog/account presentation uses domain transforms. Read the installed SDK guidance and verify adapter behavior before changing these boundaries.
Organize lib/ by domain, then use only the context files that domain needs:
index.ts contains universal implementation safe for server and client imports; it is never a re-export barrel.server.ts contains server-side implementation; keep it out of client import graphs.client.ts is a "use client" boundary for browser interaction, not an HTTP transport wrapper.action.ts is a "use server" entry point whose exports use a verb plus Action suffix.types.ts owns named shared contracts; consumers import types directly rather than through server.ts or action.ts.Subdivide large domains with the same context filenames. Put Shopify transports in their API domain's server.ts and pure transforms in index.ts, even when all current callers run on the server. Do not add descriptive sibling files, flat root implementation modules, empty entry points, forwarding exports, or barrels.
Keep storefront models in their owning domain's types.ts, such as lib/product/types.ts, lib/collections/types.ts, and lib/customer/types.ts. Shared use does not change ownership: primitives live in lib/money/types.ts, lib/media/types.ts, and lib/pagination/types.ts. Types-only domains need no index.ts or re-export barrel. Keep SDK-specific contracts under lib/shopify/ and handler-derived cart contracts in lib/cart/types.ts. Component props stay with their component; small private implementation types may stay local. Generated artifacts keep generator-owned paths and names.
The default storefront uses inline component copy and reusable content functions in lib/content/index.ts. Keep copy server-first, pass primitive labels to UI primitives and client leaves, and keep interactive copy in its consuming leaf and import shared content functions only when needed. Do not add a custom t() parser, a full browser catalog, or next-intl for a single deployment.
shopConfig.localization explicitly sets { country: "US", language: "EN", locale: "en-US" }; country/language configure commerce requests and locale configures formatting. Currency comes from Shopify. Clean URLs and one deployment are the default; lib/i18n/ and a Server Component locale resolver are absent. Operation locale/cache inputs may still be intentional. Preserve existing next-intl, catalogs, localized routes, and custom commerce behavior in upgraded installations. Use enable-i18n for copy/routing or enable-shopify-markets for regional commerce rather than coupling the two implicitly.
Shop Agent, customer authentication, and BotID are disabled by default. Preserve the installation's feature settings; a storefront redesign or localization change must not enable them implicitly.
For assistant changes, read the installed Eve docs starting at node_modules/eve/docs/README.md, then only the guide relevant to the task. Preserve Next.js deployment through withEve and the conditional plugin list passed to withShopConfig in next.config.ts.
Eve owns /eve/v1/*. Next.js prepares the browser cart through /api/agent/session; do not add another chat route or internal commerce HTTP bridge. Tool schemas and execution belong in agent/tools/, shared execution helpers in agent/lib/, and browser state, presentation helpers, and shared result types in lib/agent/. Keep Next.js request/cache APIs out of Eve's runtime imports. Use shared uncached catalog operations and Hydrogen cart handlers directly, with cart identity bound from the browser cookie rather than model arguments.
Preserve confirmed-mutation signals and Hydrogen reconciliation; restored messages must not replay cart writes or reopen the drawer. Do not claim exactly-once writes, conversation ownership, or server-history deletion on Clear. For conversation changes, check multiple search turns, visible results, and cumulative usage. For session controls, check restoration, Stop/Clear recovery, and failures. Mitigate abuse and cost with BotID, rate limits, and Gateway spending controls rather than per-session token caps. Distinguish browser/live-store evidence from mocks and build checks.
Read references/rendering-architecture.md for every route. Then read only the route references that apply:
references/commerce-flows.mdreferences/home.mdreferences/plp-search.mdreferences/pdp.mdreferences/cart-account.mdreferences/cart-provider.mdWrite down the route as five layers before editing, using commerce nouns instead of generic component names:
For each layer's full ownership boundary, see the responsibility table in references/rendering-architecture.md. For every dependency, classify it as cacheable shell content, request-time shared content, request-time personalized content, or client-only state. Draw an edge only when one result genuinely requires another. Start all other work concurrently.
Use the installed Shopify AI Toolkit for Shopify API documentation, schema facts, operation design, and validation. Invoke its API-specific skill before adding or changing Storefront or Customer Account GraphQL. For metafields or metaobjects, use its custom-data skill first.
Use shopify-graphql-reference only after Shopify validation to apply Vercel Shop conventions: operation placement, domain transforms, cache role, locale flow, invalidation, and route integration. Never treat this architecture skill as a substitute for authoritative Shopify validation.
For visible storefront changes, close the loop in a real browser before calling the work done. Use the agent's built-in browser when available; otherwise use the standalone agent-browser CLI.
agent-browser open http://localhost:3000/....agent-browser wait --load networkidle, agent-browser snapshot, and agent-browser screenshot --full.agent-browser is unavailable, say so and report the fallback checks used.Run the static hotspot scan from the skill directory:
node scripts/audit-storefront.mjs <storefront-root>
Treat its output as review prompts, not measurements. Then:
references/commerce-flows.md, including failure, empty, sold-out, and missing-media states.Report the final layer boundaries, blocking dependencies, cache ownership, and remaining risks.