Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Update 5.5-agent-skills.md
Damian Legawiec6c2b70afcc6f
diff --git a/docs/plans/5.5-agent-skills.md b/docs/plans/5.5-agent-skills.mdindex 45e2bb91a7..9c90674283 100644--- a/docs/plans/5.5-agent-skills.md+++ b/docs/plans/5.5-agent-skills.md@@ -8,7 +8,7 @@## Summary-`spree/agent-skills` is a standalone GitHub repository ([github.com/spree/agent-skills](https://github.com/spree/agent-skills)) that ships agent-readable guidance for Spree Commerce projects: 23 Claude Code skills (model-invoked, progressive disclosure), a `spree-expert` subagent for multi-step investigations, two safety hooks (block destructive db commands, warn on hardcoded secrets), and an [agents.md](https://agents.md)-spec `AGENTS.md` for cross-tool discovery.+`spree/agent-skills` is a standalone GitHub repository ([github.com/spree/agent-skills](https://github.com/spree/agent-skills)) that ships agent-readable guidance for Spree Commerce projects: 26 Claude Code skills (model-invoked, progressive disclosure), a `spree-expert` subagent for multi-step investigations, two safety hooks (block destructive db commands, warn on hardcoded secrets), and an [agents.md](https://agents.md)-spec `AGENTS.md` for cross-tool discovery.Distribution uses the [`skills`](https://github.com/vercel-labs/skills) CLI from the skills.sh ecosystem — the same channel adopted by Medusa, shadcn/ui, Anthropic, and Vercel for their respective skill sets. End users install with a single command:@@ -26,7 +26,7 @@ This is **for Spree users, not monorepo contributors.** Skills reference `backen- **Distribution channel is the [`skills`](https://github.com/vercel-labs/skills) CLI** (`npx skills add spree/agent-skills`). Tool-agnostic, supports 70+ agentic CLIs out of the box, free, automatic listing at [skills.sh](https://skills.sh). No `npm install`, no bespoke `@spree/cli` subcommand for installing skills.- **No npm package.** Skills live in the GitHub repo. Neither `create-spree-app` nor any other tool needs the path-index `dist/index.js` we previously published.- **Claude Code plugin install (`/plugin install spree@spree`) is the secondary path**, used by Claude Code users who want the two safety hooks (which `npx skills` doesn't deliver). `.claude-plugin/plugin.json` is committed in the same standalone repo so both install paths point at the same source.-- **23 skills, one subagent, two hooks.** The skill set was sized to match OrcaQubits' reference plugin parity (promotions, payments, performance, deployment, checkout, catalog, pricing, shipping, API v3, events+webhooks, SDK, i18n, legacy v2 migration, security, testing) plus Spree-specific (`spree-project`, `spree-resource`, `spree-upgrade`, `spree-data-model`, `spree-extensions`, `spree-admin`, `spree-dashboard`, `spree-storefront`).+- **26 skills, one subagent, two hooks.** The skill set was sized to match OrcaQubits' reference plugin parity (promotions, payments, performance, deployment, checkout, catalog, pricing, shipping, API v3, events+webhooks, SDK, i18n, legacy v2 migration, security, testing) plus Spree-specific (`spree-project`, `spree-customization`, `spree-resource`, `spree-decorators`, `spree-dependencies`, `spree-upgrade`, `spree-data-model`, `spree-extensions`, `spree-admin`, `spree-dashboard`, `spree-storefront`).- **`AGENTS.md` at the repo root for cross-tool discovery.** Tools that walk up from cwd looking for `AGENTS.md` (Codex CLI, Aider, Zed, Copilot, Cursor fallback) find it automatically when the user has cloned/installed into their project.- **Plugin needs a `version` field** in `.claude-plugin/plugin.json`. Without one, every commit looks like a new version to Claude Code (documented friction in `anthropics/claude-plugins-official#615`). Bump on each release, tag the commit with the matching `v<x.y.z>`.- **`create-spree-app` does NOT bundle skills into scaffolded projects.** It prints a "next steps" hint after scaffold pointing users at `npx skills add spree/agent-skills`. The scaffolded project's root `AGENTS.md` template also documents this command. Decoupling the scaffold from the skill content lets each release on its own cadence.@@ -46,7 +46,7 @@ agent-skills/│ ├── block_destructive_db.sh│ └── warn_on_secrets.sh├── skills/-│ └── <skill-name>/SKILL.md # 23 skills, each YAML frontmatter (name, description) + markdown body+│ └── <skill-name>/SKILL.md # 26 skills, each YAML frontmatter (name, description) + markdown body├── AGENTS.md # Cross-tool entry point (agents.md spec)├── README.md # User-facing install docs leading with `npx skills add`├── LICENSE # MIT@@ -55,12 +55,15 @@ agent-skills/No `package.json`, no `src/`, no TypeScript build, no `dist/`. Just content + manifests. Matches `anthropics/skills` convention.-### The 23 skills+### The 26 skills| Skill | Coverage ||---|---|| `spree-project` | General conventions, customization patterns, common commands |+| `spree-customization` | The customization decision tree — routes to decorators, events, dependencies, admin extensions, the resource generator || `spree-resource` | The `spree:api_resource` generator end-to-end |+| `spree-decorators` | Decorator patterns for extending core Spree models, controllers, helpers, services |+| `spree-dependencies` | The `Spree.dependencies` injection system (70 core + 302 API points), introspection rake tasks || `spree-api-v3` | Store vs Admin surfaces, auth (pk_/sk_/JWT), scopes, prefixed IDs, envelope, Ransack || `spree-legacy-api-v2` | Migration-focused v2→v3 (don't build new on v2) || `spree-typescript-sdk` | `@spree/sdk` + `@spree/admin-sdk` including `client.request` extension pattern |@@ -139,7 +142,7 @@ The scaffold **does not bundle skills** any more. Instead:```textAgent skills (optional)npx skills add spree/agent-skills- # Adds 23 Spree skills to whichever AI agent(s) you use+ # Adds 26 Spree skills to whichever AI agent(s) you use# (Claude Code, Codex, Cursor, Copilot, Cline, Aider, +60 others)```