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

# Agent Skills

> Teach your AI coding agent Spree's conventions — 38 installable skills, a Spree expert subagent, slash commands, and safety hooks.

[spree/agent-skills](https://github.com/spree/agent-skills) is a collection of agent skills for Spree Commerce. Skills are markdown instructions your coding agent loads on demand — they encode Spree's conventions, customization decision trees, API patterns, and upgrade flows, so the agent does things the Spree way instead of improvising from training data.

The skills work with Claude Code, Codex, Cursor, GitHub Copilot, Cline, Aider, Zed, Windsurf, OpenCode, and 60+ other agentic tools.

## Install

> [!NOTE]
>
> The skills target Spree 6. For a Spree 5 project, use the [`v0.3.0` release](https://github.com/spree/agent-skills/tree/v0.3.0) of the skills.

Projects created with [create-spree-app](https://spreecommerce.org/docs/developer/create-spree-app/quickstart.md) install every skill during setup, unless you answer no or pass `--no-agent-skills`. To add them to an existing create-spree-app project, run from the project directory:

```bash theme={"theme":"night-owl"}
npx spree add ai
```

This installs the skills release written for your Spree version (the repository tags one release per Spree version the skills changed for, such as `v6.0.1`), records it in `skills-lock.json`, and `spree upgrade` moves it along with the server. It also connects your agent to the [docs MCP server](https://spreecommerce.org/docs/developer/agentic/docs-mcp.md); pass `--no-mcp` to install only the skills. In any other project, use the skills CLI directly, pinned to the release for your Spree version:

```bash theme={"theme":"night-owl"}
npx skills add spree/agent-skills#v6.0.1
```

The [skills CLI](https://github.com/vercel-labs/skills) auto-detects which agent tools you have configured and copies the skill files into each tool's native location.

Useful variants:

```bash theme={"theme":"night-owl"}
npx skills add spree/agent-skills --list                 # see what's available without installing
npx skills add spree/agent-skills --skill spree-api-v3   # install a subset
npx skills update                                        # update installed skills later
```

## What's inside

| | |
| - | - |
| **38 skills** | Project conventions, the customization decision tree (workflow hook vs event subscriber vs provider vs dependency swap vs decorator), workflows and hooks, the v3 Store, Admin and Seller APIs, the `spree:model` / `spree:api_resource` generators, TypeScript SDKs, staff permissions, the admin dashboard and plugins, upgrades (including 5.6 → 6.0), and domain deep-dives: catalog, pricing, inventory, checkout, order totals, taxes, payments, promotions, fulfillment, returns, marketplace, B2B, multi-tenant, reporting, i18n, testing, security, performance, deployment. |
| **`spree-expert` subagent** | A Claude Code agent for multi-step investigations (upgrade audits, checkout-flow debugging, API surface planning). It researches in its own context window and returns a focused report, keeping your main session lean. |
| **2 slash commands** | `/spree:doctor` diagnoses the local dev stack (containers, env, migrations, job queues) and prescribes fixes. `/spree:audit-upgrade [version]` runs a read-only upgrade-readiness audit against your codebase. |
| **2 safety hooks** | Block destructive database commands (`db:drop`, `DROP TABLE spree_*`, mass deletes, force-pushes to main) and warn when an edit introduces a hardcoded secret (Stripe live keys, AWS keys, API tokens). Disable with `SPREE_HOOKS_DISABLE=1`. |

Skills activate automatically based on what you're working on — asking your agent to "add a Brand model with an API" pulls in the resource-generator skill; "why is this promotion not applying" pulls in the promotions skill. There's nothing to invoke manually.

## Claude Code plugin (adds commands + hooks)

The `npx skills add` path installs the skills and the subagent. The slash commands and safety hooks need the Claude Code plugin install — run inside a Claude Code session:

```text theme={"theme":"night-owl"}
/plugin marketplace add spree/agent-skills
/plugin install spree@spree
```

The plugin delivers everything the skills CLI does **plus** `/spree:doctor`, `/spree:audit-upgrade`, and the two safety hooks. Use one install path or the other — installing both makes the skills collide.

## Works in any Spree project

The skills detect your project flavor before running commands:

* **create-spree-app projects** (Docker, Rails app in `server/`) — commands route through the [Spree CLI](https://spreecommerce.org/docs/developer/cli/quickstart.md) (`spree migrate`, `spree console`, …).
* **Classic Rails apps** (Spree gems in a plain Rails app, no Docker — typical for apps created before Spree 5.4) — the skills fall back to native commands (`bin/rails`, `bundle exec rake`) from the app root.

## Updating

```bash theme={"theme":"night-owl"}
npx skills update          # skills CLI installs
```

Plugin installs update through Claude Code's plugin system (`/plugin` → check for updates). New Spree releases ship matching skill updates — update the skills when you upgrade Spree so the guidance matches your installed version.


## Related topics

- [Agentic Development](https://spreecommerce.org/docs/developer/agentic/overview.md)
- [Developing Spree](https://spreecommerce.org/docs/developer/contributing/developing-spree.md)
- [Spree TypeScript SDK quickstart for the Store API](https://spreecommerce.org/docs/developer/sdk/quickstart.md)
- [create-spree-app](https://spreecommerce.org/docs/developer/create-spree-app/quickstart.md)
- [Docs MCP Server](https://spreecommerce.org/docs/developer/agentic/docs-mcp.md)


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