--- title: Extending with Agents description: Use coding agents like Claude Code, Cursor, and Codex to personalize and extend your storefront. type: guide prerequisites: - /docs/getting-started --- # Extending with Agents Vercel Shop is built for agentic development. Instead of copy-pasting snippets from docs, you describe what you want and a coding agent handles the implementation - editing files, running commands, and validating the result. ## How it works **The template ships with structured context that agents read automatically.** `AGENTS.md` carries architecture rules and conventions - things like "every cart mutation must call `invalidateCartCache()`" or "components in `ui/` must not import domain types." Project-scoped plugins (`vercel-shop`, `vercel-plugin`, `shopify-ai-toolkit`) add template conventions, platform guidance, and authoritative Shopify documentation and validation on top. **Skills are agent-ready playbooks for specific tasks.** Each one names the files to touch, the patterns to follow, and the checks to run after. They're written and tested against the template, which means fewer hallucinations and consistent output than an ad-hoc prompt for the same task. **Not every agent integrates equally.** For best results, use an agent that reads `AGENTS.md` and supports skills and project-scoped plugins - for example [Claude Code](https://claude.ai/code), [Cursor](https://cursor.sh), or [Codex](https://openai.com/index/introducing-codex/). Claude Code has the deepest integration via the plugin install flow; Cursor and Codex lean more on the repo context and docs. ## Setting up After [creating your project](/docs/getting-started), `create-vercel-shop` installs the project plugins: * `vercel-shop` for initialization and storefront skills plus drift and upgrade-planning commands * `vercel-plugin` for generic Vercel and Next.js guidance * `shopify-ai-toolkit` for current Shopify documentation, schemas, operation validation, and store execution If you already have a project and only want the agent setup: ```bash npx create-vercel-shop@latest --no-template ``` If any plugins are missing, rerun: ```bash npx plugins add vercel/shop --scope project --yes npx plugins add vercel/vercel-plugin --scope project --yes npx plugins add Shopify/shopify-ai-toolkit --scope project --yes ``` For upgrade work, use the [`update-shop` skill](/docs/skills/update-shop). The `vercel-shop` plugin carries a template rollout log so agents can reason about change-level updates instead of guessing from a single scaffold version. New scaffolds record bootstrap metadata so agents can compare rollout entries against when a project was created. To initialize a storefront from an agent, use the `init-vercel-shop` skill and provide an explicit target directory. The skill delegates filesystem changes to `create-vercel-shop`, verifies the generated project, and can use Shopify CLI to connect an existing store or fall back to the Headless channel. ## Custom blocks in AGENTS.md Some sections of `AGENTS.md` are managed by external tools and wrapped in HTML comment markers: ```md ## This is NOT the Next.js you know ... ``` The owning tool can overwrite the content between `BEGIN` and `END` on upgrade without touching your custom instructions. To drop an opinionated block, delete everything from `BEGIN` to `END` - the rest of the file stays intact. The template ships with two blocks: | Block | Owner | What it contains | | -------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `nextjs-agent-rules` | Next.js | Reminds agents this Next.js version has breaking changes and to read bundled docs before writing code. Refreshed on Next.js upgrade. | | `vercel-shop-style` | Vercel Shop | Code style conventions: alphabetized exports and keys, no barrel files, push `"use client"` to leaves, naming rules, Tailwind patterns. Remove the block if your team prefers different conventions. | Everything outside these markers is yours. Add team conventions or domain constraints anywhere else and no upgrade will overwrite them. ## Skills To run a storefront skill in Claude Code: ```bash /vercel-shop:enable-shopify-markets ``` For a new project: ```bash /vercel-shop:init-vercel-shop ``` In Cursor or Codex, describe the task and reference the matching skill doc when helpful: ``` Enable multi-locale support with Shopify Markets ``` You can also follow any skill manually from the docs, or inspect the source in the `vercel/shop` repository. Source-backed storefront architecture and commerce behavior. Multi-locale and multi-currency support. ## Working effectively with an agent Skills cover the common path. Most of your work will be ad-hoc prompts - restyle the PDP, add a wishlist, integrate a review system. A few habits make this go much smoother. **Let the agent propose first.** Before any code gets written, ask for the plan: ``` Add a size guide to the PDP. Before writing code, tell me your plan. ``` A good proposal names the files it will touch, the patterns it will follow, and how it will validate the result. Redirect there - not after the diff lands. **Be specific about what, where, and when.** Vague prompts get vague code. Compare `add size guide` with: ``` Add a size guide accordion below the product description on the PDP. Pull sizing data from a product metafield called "sizing_guide". Only show the section when the metafield exists. ``` The second version names the placement, the data source, and the empty-state behavior - all things the agent would otherwise guess. **Iterate with targeted follow-ups.** After the first pass, refine in place rather than re-prompting the whole task: ``` Make the accordion closed by default on mobile ``` The agent retains context from the previous exchange. **Use a browser feedback loop.** Storefront changes should be checked in a real browser, not only by reading diffs. v0 has this feedback loop built in. For agents without built-in browser control, install the standalone [`agent-browser`](https://github.com/vercel-labs/agent-browser) CLI: ```bash npm install -g agent-browser agent-browser install ``` Then ask the agent to start the dev server, open the affected route, capture a snapshot and screenshot, interact through the changed commerce flow, and repeat until the browser result matches the intended behavior: ```bash agent-browser open http://localhost:3000/products/example agent-browser wait --load networkidle agent-browser snapshot agent-browser screenshot --full ``` **When something breaks, name the failure.** Specific error messages and likely files beat "fix it": ``` The build fails with "Type 'string' is not assignable to type 'Money'". Check the transform in lib/shopify/transforms/product.ts. ``` ## Try it yourself Ideas worth a single agent prompt - describe the outcome and let the agent work out the implementation. * **Recently viewed** — a carousel of the last few products a shopper visited, backed by `localStorage`. * **Narrower product grid** — 3 columns instead of 4 on desktop, without touching the mobile layout. * **Back to top button** — appears once the shopper scrolls past the fold. * **Promotional banner** — dismissible, driven by a metafield on the shop object. * **Product reviews** — from a metafield, or integrated with a service like Judge.me. * **Wishlist** — heart icons on cards and the PDP, a saved-products page, synced across tabs via `localStorage`. * **Swap search providers** — Algolia instead of built-in Shopify search, same filter sidebar. --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)