Agent skills

Ready-made instructions for AI agents: how to build sites, themes, catalog and checkout on ItemShop.

A skill is a bundle of instructions and examples an AI agent loads when the task calls for it — e.g. “change the site colors” or “move my shop off the configurator”. Skills teach the agent ItemShop conventions (SDK, site.config.ts, checkout rules) so it doesn’t have to guess.

Each skill is a folder in the Agent Skills format: a SKILL.md (name and a description of when to use it) plus references/ and examples/ that the agent loads only when needed. Skills are open source (MIT) in the itemshop-sdk repository, skills/ directory.

Catalog

Skill	Use it for
itemshop-storefront	Start here. Project layout, itemshop.site.json, site.config.ts and the edit → build → preview → publish loop.
itemshop-theme	Colors, fonts, layout, light/dark theme, accessibility, mobile and a pre-publish quality checklist.
itemshop-catalog	Products, categories (servers), variants, bonus packages, prices, translations, plus discount codes and vouchers via MCP.
itemshop-checkout	What must never change in cart and checkout (consents, Turnstile, payment redirect, status by number and key, payment groups) and how to style it safely.
itemshop-seo	Title and description, Open Graph, canonical/hreflang, JSON-LD, sitemap, performance.
itemshop-migrate-legacy	Moving settings from the old configurator into site.config.ts.
itemshop-sdk	The official SDKs (TS, Python, PHP, Java/Kotlin, Go) in bots, plugins and custom sites.

The catalog is also available as an API (GET /skills) and via npx itemshop skills list.

Before you install

Skills tell the agent how to do something; the MCP server gives it the tools to do it on your shop. Connect MCP first (npx itemshop mcp config --agent <id> prints the config, and Workspace → Agent in the panel has copy-ready snippets).

Installation

Built-in agent

Nothing to install — skills load automatically.

Claude Code

npx itemshop skills add itemshop-storefront        # → .claude/skills/itemshop-storefront
npx itemshop skills add itemshop-theme --force     # update

Or copy the folder by hand into .claude/skills/<id>/ (project, shared via git) or ~/.claude/skills/<id>/ (personal). Claude loads descriptions at start and the full skill when the task matches; /itemshop-theme invokes one by name.

Codex, OpenCode, Gemini CLI, Cursor, Windsurf, Aider

These agents don’t load SKILL.md natively, so install the folders in the repo and point the agent’s instruction file at them:

npx itemshop skills add itemshop-storefront --dir .itemshop/skills
npx itemshop skills add itemshop-theme --dir .itemshop/skills

Add to AGENTS.md (Codex, OpenCode, Cursor, Windsurf), GEMINI.md (Gemini CLI) or CONVENTIONS.md (Aider):

## ItemShop skills
This is an ItemShop storefront project. Before changing it, read `.itemshop/skills/itemshop-storefront/SKILL.md`.
Then read the matching skill for the task and load its `references/` only when needed:
- look & feel -> `.itemshop/skills/itemshop-theme/SKILL.md`
- products/prices/discounts -> `.itemshop/skills/itemshop-catalog/SKILL.md`
- cart/checkout -> `.itemshop/skills/itemshop-checkout/SKILL.md` (never change consents, Turnstile or the payment redirect)
- SEO/performance -> `.itemshop/skills/itemshop-seo/SKILL.md`
- moving old settings -> `.itemshop/skills/itemshop-migrate-legacy/SKILL.md`
- SDK usage -> `.itemshop/skills/itemshop-sdk/SKILL.md`

The panel (Workspace → Agent) generates this block together with the MCP config for the chosen agent. Cursor can instead use a .cursor/rules/*.mdc rule with the same text.

MCP server

Tools and tokens.

Connecting agents

Step-by-step agent setup.