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.

This works because the template ships with structured context that agents read automatically:

• AGENTS.md - architecture rules and conventions. Tells the agent things like "every cart mutation must call invalidateCartCache()" or "components in ui/ must not import domain types."
• Project-scoped plugins - vercel-shop, vercel-plugin, and shopify-ai-toolkit provide skills, platform guidance, and live Shopify schema tooling.

For best results, use an agent that reads AGENTS.md and supports skills and project-scoped plugins - for example Claude Code, Cursor, or 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, create-vercel-shop installs the project plugins:

• vercel-shop for storefront skills plus bootstrap, drift, and upgrade-planning commands
• vercel-plugin for generic Vercel and Next.js guidance
• shopify-ai-toolkit for Shopify-aware tooling and schema access

If you already have a project and only want the agent setup:

npx create-vercel-shop@latest --no-template

If any plugins are missing, rerun:

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, the vercel-shop plugin also 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.

Custom blocks in AGENTS.md

Some sections of AGENTS.md are managed by external tools and wrapped in HTML comment markers:

<!-- BEGIN:nextjs-agent-rules -->

## This is NOT the Next.js you know

...

<!-- END:nextjs-agent-rules -->

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:

Everything outside these markers is yours. Add team conventions or domain constraints anywhere else and no upgrade will overwrite them.

Skills

Skills are agent-ready playbooks - markdown files that describe exactly how to complete a specific task. 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.

To run a storefront skill in Claude Code:

/vercel-shop:enable-shopify-markets

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.

Available skills

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.

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.