> ## Documentation Index
> Fetch the complete documentation index at: https://andcze.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://code.claude.com/docs/en/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](https://andcze.mintlify.site/en/developers/mcp.md) 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**

```bash theme={null}
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:

```bash theme={null}
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):

```markdown theme={null}
## 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](https://andcze.mintlify.site/en/developers/mcp.md)**
>
> Tools and tokens.

> **[Connecting agents](https://andcze.mintlify.site/en/site/agents.md)**
>
> Step-by-step agent setup.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.