‹ Back to apps
SC
Spree Commerce
Agent skills for building on Spree Commerce 6, the open-source B2B and marketplace ecommerce platform: API v3, checkout, catalog, B2B, marketplace, payments, deployment and more.
What’s inside
38 skills- Skillspree-api-v3Use when the user is calling or debugging Spree 6's REST API v3 — the Store API (storefronts, mobile apps, customers), the Admin API (integrations, back-office tools) or the Seller API (marketplace sellers). Covers auth (publishable/secret keys, JWT audiences), scopes and permissions, prefixed IDs, the cart → order split, checkout `requirements[]`, order statuses, the `{data, meta}` envelope, expand/fields, Ransack filters, errors, idempotency, localization headers and rate limits. Common phrasings include "Spree API", "Store API", "Admin API", "publishable key", "secret key", "X-Spree-Api-Key", "X-Spree-Token", "API scopes", "403 required_scope", "cart_ vs or_", "complete cart", "cart 404 after checkout", "prefixed IDs", "expand", "Idempotency-Key", "429 rate limit", "v3 endpoint". For ADDING a new endpoint use spree-resource; for roles/permissions internals use spree-auth-permissions.
- Skillspree-auth-permissionsUse when the user is working on who can sign in to Spree 6 and what they may do — staff roles and permission keys, secret-key scopes, registering permission scopes for an extension, 403 errors with `required_permission` / `required_scope`, storefront ownership rules (`Spree::Storefront::AccessPolicy`), custom login strategies (SSO, OIDC, Auth0/Okta/Entra/Firebase), JWT audiences, or swapping the customer/admin user class. Common phrasings include "Spree roles", "staff permissions", "add a role", "read_orders permission", "Spree.permissions.register_scope", "API key scopes", "403 Missing permission", "who can see this order", "SSO for the dashboard", "OIDC login", "custom authentication strategy", "Spree.customer_class", "admin_user_class", "CanCanCan in Spree 6". Spree 6.
- Skillspree-b2bUse when building B2B or wholesale commerce on Spree 6 — the end-to-end "build a B2B store" setup, companies/buyer organizations (company trees, divisions, members, invitations, company address book, buying on a company's behalf), catalogs and negotiated pricing (assortments, owned price lists, percentage adjustments, catalog assignment to companies or customer groups, channel default catalogs), customer groups, gated storefronts (`storefront_access` login_required / prices_hidden), the Next.js wholesale portal, minimum order quantity / order multiples / order minimums, PO numbers, and orders on account (pay by invoice, staff-keyed draft orders with negotiated prices, `payment_pending`), and freight shipping (cartons, pallets, unpriced freight rates). Common phrasings include "B2B", "wholesale", "build a B2B store", "pay by invoice", "net terms", "negotiated line price", "draft order for a company", "trade customers", "company account", "Spree::Company", "division", "buyer organization", "negotiated prices", "customer-specific pricing", "catalog", "price list per company", "MOQ", "minimum order quantity", "order multiple", "case pack", "order minimum", "PO number", "purchase order reference", "login to see prices", "members-only store", "wholesale portal", "X-Spree-Channel", "freight", "pallet", "carton".
- Skillspree-catalogUse when the user is working with the Spree 6 product catalog — products, variants, option types/values, the default variant, product types (templates), categories vs collections, custom fields, media (images, video, media library), channel publications, search providers (database, spree_meilisearch, custom), digital assets, or catalog imports/exports. Common phrasings include "create a product", "add variants", "size and color options", "product type", "category tree", "collection", "brand", "custom field on products", "product images", "product video", "primary_media", "product not showing in store", "publish product on channel", "Meilisearch", "reindex", "custom search provider", "digital download", "master variant". Covers the catalog graph and how to read/write it from Ruby, the Admin SDK and `spree api`.
- Skillspree-checkoutUse when the user is working on Spree 6 checkout — the Cart → Order split, checkout requirements and advisory steps, `Spree::Checkout::Registry` (add_requirement / register_step / base_steps), cart completion (`Spree::Carts::Complete`), `carts.complete` / `carts.add_item` workflow hooks, addresses, payment sessions, guest checkout, cart association/merge on login, or the Store API / `@spree/sdk` checkout sequence. Common phrasings include "checkout broken", "cart won't complete", "why can't this cart complete", "add a checkout step", "require a field before checkout", "require terms acceptance", "skip the delivery step", "order stuck", "double charge", "guest checkout", "cart not found after checkout", "merge carts on login", "custom checkout validation", "block checkout if…". Covers where each customization belongs and how completion guarantees idempotency.
- Skillspree-cliUse when calling the Spree 6 Admin API from the command line or driving it programmatically as an agent — exploring endpoints, reading or mutating store data, and especially DEBUGGING (inspecting an order/product/customer, checking why a request failed, reproducing a 403/422). The `spree api` command group in `@spree/cli` is a `gh api`-style generic HTTP client: `spree api get|post|patch|delete <path>` plus offline discovery (`spree api endpoints`, `spree api schema`). Common phrasings include "spree api", "spree CLI", "call the admin API from the terminal", "spree api get", "inspect this order", "why is this Spree request failing", "list admin endpoints", "spree auth". Also covers the project-side dev commands agents reach for while debugging (`spree shell`, `spree rspec`, `spree console`, `spree add`, `spree plugin new`). For SDK/TypeScript integration use spree-typescript-sdk; for raw API protocol details use spree-api-v3.
- Skillspree-customizationUse FIRST when a Spree 6 customization is on the table and the right pattern isn't obvious — "how do I customize X", "where should this logic go", "decorator or subscriber?", "hook or event?", "how do I block checkout when…", "add a field to products", "change how tax/shipping/search works", "extend Spree without forking". A decision tree that routes each need to the right extension point (store settings, SPREE_* config, model preferences, workflow hooks, events, webhooks, Checkout::Registry, providers, custom fields vs metadata, validators, permitted attributes, permission scopes, new resources, dependencies, decorators, dashboard plugins) and to the skill that covers it in depth.
- Skillspree-dashboard-pluginsUse when packaging Spree 6 React dashboard customizations as a redistributable npm plugin (optionally paired with a Rails extension gem) that other Spree stores install — scaffolding with `npx @spree/cli plugin new`, file routes and route collisions, peerDependencies against `@spree/dashboard-core`/`-ui`, prebuilt vs source publishing, `sideEffects`, the `spree.dashboard.plugin` package.json marker, auto-discovery via `virtual:spree-dashboard-plugins` vs an explicit whitelist, Tailwind class scanning, `definePlugin(config)` factories, Changesets, and the backend gem half. Common phrasings include "publish a dashboard plugin", "npm package for the Spree admin", "spree plugin new", "share admin screens across stores", "plugin not showing up", "Dashboard route collision", "plugin styles missing", "marketplace extension with admin UI".
- Skillspree-dashboardUse when customizing the Spree 6 admin — the React dashboard (`@spree/dashboard`, Developer Preview) in `apps/dashboard/` — from inside the project. Covers `defineDashboardPlugin` in `src/plugins.ts`, sidebar/settings nav, custom pages/routes, slot widgets on built-in pages, table columns/filters, extension form fields and custom field widgets, permission gating, calling the Admin API (`adminClient`, store-scoped query keys, 422 mapping), exposing a new attribute end-to-end, theming tokens, translations, Vitest/Playwright tests and deployment. Common phrasings include "add a page to the admin", "admin sidebar item", "add a column to the products table", "add a card to the product page", "custom field on the product form", "hide menu item by permission", "restyle the admin", "dashboard plugin", "spree add dashboard", "React admin", "where did spree_admin go".
- Skillspree-data-modelUse when the user asks how Spree 6's domain models relate or where something is stored — Store/Channel/Market/Catalog, Product/Variant/Price/Category/Collection, Customer/Company/CustomerGroup, Cart vs Order, LineItem, TaxLine/Discount/Fee, Fulfillment/DeliveryMethod/StockLevel, Return/Exchange/Claim, Payment/PaymentSession/Refund/StoreCredit/GiftCard, Seller/OrderGroup, prefixed ID prefixes and document numbers. Phrasings: "how does X connect to Y", "what's the difference between Cart and Order", "Store vs Channel vs Market", "what statuses can a fulfillment have", "what prefix is `ful_`", "where are taxes stored", "how do I query orders". Architecture and relationships — for adding new models use spree-resource; for behavior use the domain skill (spree-checkout, spree-fulfillment, …).
- Skillspree-decoratorsUse when the user wants to extend an existing Spree 6 model or API controller without forking — add an association to Spree::Product, add a validation or scope, add a method to Spree::Cart / Spree::Order, narrow what an API v3 endpoint returns, permit an extra attribute on writes. Common phrasings include "add brand to product", "decorate Spree::X", "ProductDecorator", "OrderDecorator", "Module#prepend", "spree:model_decorator", "spree:controller_decorator", "extend an existing Spree model", "add a method to Spree::Order", "override Spree behavior", "monkey patch Spree", "customize an API controller". Provides the decorator pattern, the generators, the prepended(base) idiom, API controller decorators and the gotchas — and routes behavioral changes to workflow hooks, events or dependencies instead.
- Skillspree-dependenciesUse when the user wants to replace a whole Spree 6 service, workflow or API serializer with their own class — swap the add-to-cart workflow, checkout completion, cart totals recalculation, order status writer, storefront access policy, or an API v3 serializer. Common phrasings include "Spree.dependencies", "Spree::Dependencies", "swap a service", "replace Spree::Carts::AddItem", "cart_add_item_workflow", "carts_complete_workflow", "cart_recalculate_totals_workflow", "storefront_access_policy_class", "override an API serializer", "Spree.api.product_serializer", "dependency injection in Spree", "spree:dependencies:list", "spree:dependencies:overrides", "my cart_add_item_service override stopped working", "what can I swap". Covers when a swap is justified (usually a workflow hook is better), subclassing a shipped workflow, service vs workflow seams, legacy *_service keys that are stashed not applied, API serializer seams, per-controller overrides, and the introspection rake tasks.
- Skillspree-deploymentUse when deploying a Spree 6 application to production or scaling it — Docker image builds, Render/AWS/Railway/Kubernetes/VPS, required environment variables, Solid Queue (jobs in Puma vs a dedicated `bin/jobs` worker), Solid Cache, optional Sidekiq/Redis, the Mission Control `/jobs` dashboard, serving the React dashboard at `/dashboard` or from a static host, migrations on boot and `spree:upgrade`, S3/R2 storage, CDN_HOST, Meilisearch, PostgreSQL/MySQL/SQLite, and observability (spree_opentelemetry, Sentry). Common phrasings include "deploy Spree", "Spree Docker image", "spree build --production", "Render deploy", "Spree environment variables", "split the worker", "SOLID_QUEUE_IN_PUMA", "jobs not running", "/jobs dashboard locked", "dashboard 404 in production", "images point at localhost", "S3 setup", "Sidekiq instead of Solid Queue", "OpenTelemetry tracing". Spree-specific bits only — generic Rails deployment is out of scope.
- Skillspree-events-webhooksUse when the user wants Spree 6 to react to something that happened — sync placed orders to an ERP/WMS, send a notification, keep an audit trail, fire outbound webhooks, configure webhook endpoints, verify webhook signatures, or debug a subscriber or delivery that never arrived. Common phrasings include "when an order is placed", "react to X", "Spree events", "subscriber", "publish_event", "publishes_lifecycle_events", "order.placed", "order.completed", "webhook endpoint", "X-Spree-Webhook-Signature", "HMAC", "webhook retry", "webhook disabled", "webhook.test", "audit log / state changes". Covers in-process subscribers AND outbound webhooks, and when to use a workflow hook instead.
- Skillspree-extensionsUse when installing a Spree gem (spree_stripe, spree_easypost, spree_meilisearch, spree_opentelemetry, spree_i18n, spree_adyen, spree_multi_store…) or building your own reusable Spree 6 extension — a gem (Rails engine) for models, API endpoints, permissions, hooks and providers, paired with a dashboard plugin (npm package) for admin screens. Common phrasings - "add Stripe", "install spree_X", "create a Spree extension", "build a gem for Spree", "spree-extension create", "share this across apps", "register a provider from my gem", "engine initializer", "after_initialize vs to_prepare", "extension migrations". For single-app customization start with spree-customization — most work doesn't need a gem.
- Skillspree-fulfillmentUse when working with how Spree 6 gets goods to the customer — fulfillments (`ful_`), delivery methods, delivery zones, delivery profiles and origin groups, delivery rates, calculators and carrier rate providers (EasyPost, freight), order routing and stock splitters, partial fulfillment and splitting, shipping labels, tracking/deliveries, carrier tracking webhooks, pickup and digital delivery. Common phrasings include "shipping method", "no delivery rates at checkout", "ship from the nearest warehouse", "custom shipping calculator", "live carrier rates", "mark as shipped", "partial shipment", "tracking number", "carrier webhook", "click and collect", "3PL / WMS integration", "fulfillment stuck unfulfilled", "add a fulfillment status", "fulfillment.fulfilled event", "Spree::Shipment". Returns/exchanges/claims live in spree-returns; stock counts, reservations and transfers in spree-inventory.
- Skillspree-i18nUse when translating a Spree 6 store — adding a locale, translating product/category/collection content, fixing missing translations, building a multilingual storefront, syncing translations from a TMS via the Admin API, making a custom model translatable, working with Mobility, or wrangling `Spree.t` / dashboard i18next keys. Common phrasings include "add Spanish to Spree", "translate products", "Mobility", "translation tables", "RTL", "missing translation", "Spree.t", "fallback locale", "translated slugs", "translations API", "translate dashboard plugin", "X-Spree-Locale".
- Skillspree-inventoryUse when working with stock in Spree 6 — StockLevel counters (count_on_hand, allocated_count, reserved_count, incoming_count, available/purchasable), stock locations (kind, pickup_enabled, returns_enabled), stock movements and their kinds, checkout stock reservations and their expiry job, backorders, inventory tracking on/off, bulk stock sync from an ERP/WMS (bulk_upsert), stock transfers, suppliers, purchase orders and stock receipts, the spree:stock:recount_levels task, and stock_level events. Common phrasings include "stock count is wrong", "oversold", "sync inventory from ERP", "update stock via API", "reserve stock at checkout", "stock reservation expired", "backorder", "restock", "move stock between warehouses", "purchase order", "receive a delivery", "incoming stock", "StockItem", "count_on_hand", "out of stock".
- Skillspree-marketplaceUse when building or extending a multi-vendor marketplace on Spree 6 — sellers/vendors, seller onboarding requirements, seller product review (submit/approve/reject), split checkout into order groups, commissions (rates, rules, commission lines, commission tax), seller payouts and the transfer/payout ledger, Stripe Connect, a custom payout provider, the seller panel (`@spree/seller-dashboard`), or the Seller API (`/api/v3/seller`, `@spree/seller-sdk`). Common phrasings include "marketplace", "multi-vendor", "vendor", "seller", "Spree::Seller", "invite/approve a seller", "onboarding checklist", "seller requirements", "order group", "isOrderGroup", "split order per seller", "commission rate", "commission line", "seller payout", "payout provider", "SweepDueJob", "Stripe Connect", "seller API", "X-Spree-Seller-Id", "seller dashboard".
- Skillspree-multi-tenantUse when building a SaaS / multi-tenant platform on Spree 6 with the Enterprise `spree_multi_tenant` gem — many isolated merchants on one deployment, each with its own stores, catalog, customers and orders. Covers licensing and install (`spree_enterprise:install`, `spree_multi_tenant:install`), `Spree::Tenant` and row-level `tenant_id` isolation, `SpreeMultiTenant::Base`, `with_tenant` / `without_tenant`, console tenant context, `insert_all`/`upsert_all` pitfalls, background jobs, `Spree.root_domain`, cookie domain and host authorization, global staff vs per-tenant customers. Common phrasings include "multi-tenant Spree", "SaaS on Spree", "each merchant gets a subdomain", "tenant isolation", "records leaking between tenants", "set the tenant in the console", "Blocked hosts lvh.me".
- Skillspree-order-totalsUse when the user is working with money on a Spree 6 cart or order — how `total` is built, the typed money rows (`Spree::TaxLine`, `Spree::Discount`, `Spree::Fee`), totals columns (`item_total`, `discount_total`, `delivery_total`, `fee_total`, `included_tax_total` vs `additional_tax_total`, `adjustment_total`, `amount_due`), `Spree::Carts::RecalculateTotals`, custom adjusters (`Spree.adjusters`), fees and customs duties, manual discounts and fees on placed orders, or rendering an order summary. Common phrasings include "order total is wrong", "totals don't add up", "tax counted twice", "add a surcharge / handling fee / gift wrap fee", "add a custom fee", "where are adjustments", "Spree::Adjustment missing", "recalculate order totals", "edit a placed order's discount", "why did my discount disappear", "display_total", "money as string", "duties".
- Skillspree-paymentsUse when the user is working with Spree 6 payments — payment methods and gateways (Stripe, Adyen, PayPal, Razorpay), session-based vs direct (offline) payment methods, payment sessions and payment setup sessions (saved cards), payment statuses, capture timing (checkout / on_dispatch / manual), capture and void, refunds, gateway webhooks, building a custom payment method, store credits and gift cards, and payment events. Common phrasings include "add payment gateway", "install Stripe", "custom payment method", "payment session", "client_secret", "3D Secure", "offsite redirect", "customer closed the tab", "payment webhook", "capture on shipment", "authorize only", "manual capture", "refund an order", "store credit", "gift card", "payment failed", "payment stuck", "payment.paid", "order.paid", "cash on delivery", "bank transfer", "purchase order".
- Skillspree-performanceUse when investigating or improving Spree 6 performance — slow cart writes, slow checkout, slow Store API product listings, N+1 queries in custom endpoints or serializers, search latency, Meilisearch indexing floods, image processing backlogs, Solid Queue/Sidekiq queue tuning, HTTP/CDN caching of the Store API, dashboard data-fetching, or tracing with OpenTelemetry. Common phrasings include "slow cart", "add to cart is slow", "tax provider called too often", "N+1 in Spree", "slow product listing", "search slow", "Meilisearch reindex", "import is starving jobs", "jobs backlog", "queue tuning", "Spree cache", "CDN caching API", "trace a checkout", "find the slow workflow step".
- Skillspree-pricingUse when the user is working with Spree 6 pricing — variant prices per currency (price_in, amount_in, set_price), compare-at/sale prices, multi-currency, price lists and price rules (market, channel, volume), catalog-owned price lists for B2B/wholesale, percentage price adjustments, quantity breaks / volume pricing, scheduled sales, the pricing context and resolution order, external pricing providers, bulk price updates, and EU Omnibus price history (prior_price). Common phrasings include "set price", "variant.price", "compare at price", "sale price", "price list", "wholesale pricing", "customer-specific price", "volume discount", "tiered pricing", "quantity break", "schedule a sale", "multi-currency", "wrong price shown", "prior price", "Omnibus", "lowest price in 30 days", "bulk update prices".
- Skillspree-projectUse for any work in a Spree Commerce 6 project — orienting in the repo (server/, apps/dashboard, apps/storefront), detecting the project flavor (create-spree-app + `spree` CLI vs a classic Rails app), running commands, following Spree conventions (Spree:: namespace, Spree.base_class, Spree.customer_class, current_store scoping, has_status, prefixed IDs, custom fields vs metadata), and finding the right docs. Activates broadly — "how does Spree work", "where do I put this", "how do I run X in my Spree app", "what are the Spree conventions", "set up a Spree project". Routes to spree-customization when the question is which extension pattern to use.
- Skillspree-promotionsUse when the user is working with Spree 6 promotions and discounts — creating promotions (automatic or coupon code), bulk/multi-use coupon codes, promotion rules and actions, calculators, how competing promotions are resolved, manual discounts, writing a custom promotion rule, action or calculator, or a custom adjuster. Common phrasings include "create promotion", "coupon code", "discount code", "generate 1000 codes", "BOGO", "free shipping promotion", "10% off category", "promotion not applying", "custom promotion rule", "custom promotion action", "custom calculator", "stack promotions", "best discount wins", "manual discount", "goodwill discount", "Spree::Discount", "Taxon rule".
- Skillspree-providersUse when connecting Spree 6 to an external system through a provider contract — a tax engine, carrier rate shopping, a WMS/3PL or label provider, a payment gateway, a search engine (Meilisearch, Typesense, Algolia), seller payouts, digital downloads/license keys, SSO/OpenID Connect or a custom JWT issuer, OpenTelemetry/APM, or an ERP/PIM/DAM. Common phrasings - "custom tax provider", "Avalara", "delivery rate provider", "EasyPost", "fulfillment provider", "custom payment method", "search provider", "payout provider", "digital asset provider", "SSO", "Okta/Entra login", "Spree::Integration", "store credentials for a provider", "Spree.integrations", "which registry do I append to". A map of every plug-in point - base class, registration call, where it is selected, and the doc to read.
- Skillspree-reportingUse when adding or changing analytics, reports, dashboard numbers, or CSV imports/exports in a Spree 6 project. Covers the `Spree.reporting` semantic layer (metrics, dimensions, counters, bases, `replace: true` overrides), `Spree::Reporting::Query`, authorization via `subject` + `key_scope`, saved reports (`Spree::SavedReport`), and the async CSV pipeline (`Spree::Export` / `Spree::Import` subclasses, import statuses, retrying failed rows, resumable processing). Common phrasings include "add a custom metric", "report sales by brand/seller/warehouse", "add a dashboard counter", "why don't the report rows add up to the total", "export orders to CSV", "add a custom export/import type", "import products from a spreadsheet", "retry failed import rows".
- Skillspree-resourceUse when the user wants to add a new model, database table, or REST API endpoint to a Spree 6 project. Covers `spree:api_resource` (model + migration + Store/Admin API controllers + serializers + factory + controller specs + routes + permission scope) and `spree:model` (model + migration only). Common phrasings include "add a Brand model", "create a new resource", "expose X as an API endpoint", "add an Admin API for Y", "scaffold a Spree resource", "create a Spree model without an API", "internal model", "make my model store-scoped".
- Skillspree-returnsUse when working with post-purchase flows in Spree 6 — returns (money back), exchanges (different items), and claims (damaged / missing / wrong item, refund or replacement without the goods coming back). Covers Spree::Return / Spree::Exchange / Spree::Claim, their statuses and workflows, return windows per market and staff overrides, custom return policy via the returns.create.validate hook, receiving and restocking (resellable), refunds to the original payment vs store credit, prepaid return labels, return and claim reasons, events, and the Store/Admin API endpoints. Common phrasings include "RMA", "return window", "30-day returns", "final sale items can't be returned", "restock returned items", "refund a return", "store credit refund", "exchange for a different size", "item arrived damaged", "send a replacement", "return label", "ReturnAuthorization", "CustomerReturn", "Reimbursement".
- Skillspree-securityUse when the user is hardening a Spree 6 app, reviewing a PR or finding for security issues, managing secrets and API keys, configuring CORS/CSP, securing the dashboard or /jobs, handling GDPR data requests, or asking about Spree-specific risks (publishable vs secret keys, scope minimization, IDOR on carts/orders, rich-text XSS, webhook HMAC and SSRF, encrypted columns, PCI scope). Common phrasings include "Spree security", "leaked secret key", "rotate API key", "CORS", "Allowed Origins", "CSP", "XSS in product description", "IDOR", "cross-store data leak", "mass assignment", "permitted attributes", "webhook signature", "SSRF", "Active Record encryption", "GDPR", "anonymize customer", "PCI", "Mission Control password". For roles, permission keys and login strategies use spree-auth-permissions.
- Skillspree-storefrontUse when the user is working on the optional Next.js storefront for Spree 6 (the customer-facing store in `apps/storefront/`, github.com/spree/storefront) — adding a page, customizing checkout, fetching products, multi-region URLs, the wholesale/B2B portal, transactional emails from webhooks, storefront tests, or integrating any frontend with the Store API via `@spree/sdk`. Common phrasings include "customize storefront", "Next.js storefront", "frontend changes", "PDP", "product page", "cart", "checkout flow", "order confirmation page", "@spree/sdk", "publishable key", "country/locale URLs", "wholesale portal", "storefront emails", "webhook route". Provides the storefront architecture, the @spree/sdk integration model, and the storefront-vs-backend decision tree.
- Skillspree-taxesUse when the user is configuring or extending tax in Spree 6 — tax categories (`tax_code`), tax rates by `country_code`/`state_code`, VAT-inclusive vs added-on pricing (`included_in_price`, market `tax_inclusive`), per-market tax providers and `Spree.default_tax_provider`, writing a custom tax provider (`estimate`/`commit`/`void`/`refund`), `Spree::TaxLine` rows, the `carts.recalculate_totals.set_tax_line_context` hook, B2B tax identifiers (VAT numbers) and exemption certificates, or connecting Avalara/an external tax engine. Common phrasings include "tax not calculated", "tax is zero", "VAT included in price", "EU VAT", "US sales tax", "tax per state", "integrate Avalara / TaxJar / Stripe Tax", "custom tax calculation", "tax exempt customer", "reverse charge", "VAT number at checkout", "tax on shipping", "tax on fees".
- Skillspree-testingUse when the user is writing or running automated tests for a Spree 6 app or extension — model specs, workflow/hook specs, subscriber specs, API v3 controller/request specs, factories, and dashboard (Vitest/Playwright) tests. Covers RSpec + Factory Bot (not Minitest/fixtures), spree_dev_tools, Spree's factories (:cart, :cart_ready_to_complete, :completed_order_with_totals …), the 'API v3 Store' / 'API v3 Admin' shared contexts, Spree::Current.store in tests, `spree rspec`, and common failures. Common phrasings include "test my Spree model", "Spree spec", "Spree factories", "spree_dev_tools", "include_context API v3", "test a workflow hook", "test a subscriber", "OrderWalkthrough", "Store must exist", "spree rspec", "dashboard tests".
- Skillspree-typescript-sdkUse when the user is building a TypeScript or JavaScript client against Spree 6 — a Next.js storefront, a mobile/web app, an integration or back-office tool, a webhook receiver. Covers @spree/sdk (Store API), @spree/admin-sdk (Admin API) and points to @spree/seller-sdk (marketplace). Common phrasings include "Spree SDK", "createClient", "createAdminClient", "store client", "admin client", "cart token / spreeToken", "carts.complete", "orders.get after checkout", "TypeScript types from Spree", "Zod schemas", "verifyWebhookSignature", "retry config", "client.request custom endpoint", "MSW Spree", "@spree/sdk", "@spree/admin-sdk". For curl/raw HTTP and protocol details, see spree-api-v3.
- Skillspree-upgrade-5-to-6Use when upgrading a Spree 5.x application to Spree 6.0, or when fixing code that broke after that upgrade. Common phrasings include "upgrade to Spree 6", "migrate from 5.6 to 6.0", "Spree 6 breaking changes", "checkout_flow / state machine is gone", "Spree::Adjustment not found", "master variant removed", "PermissionSets NameError", "staff locked out after upgrade", "what replaced Shipment / Taxon / ReturnAuthorization / metafields", "spree_admin gem not found". Covers preconditions (5.6 first, Rails 8.1, Gemfile swaps, roles as data), the ordered 5.6 → 6.0 data backfills, grep recipes for code that must change, and the behavioral review checklist.
- Skillspree-upgradeUse when the user wants to upgrade Spree to a newer version, or asks how the upgrade machinery works. Common phrasings include "upgrade Spree", "bump Spree", "how do I upgrade", "what's the upgrade process", "run the Spree upgrade", "spree upgrade --plan", "rake spree:upgrade", "re-run one upgrade step", "upgrade in production / release phase". Covers the version-agnostic flow for Spree 6 projects — the `spree upgrade` CLI, the `rake spree:upgrade` task and its manifests, retrying single steps, and running backfills in production. For the Spree 5.x → 6.0 major hop, also load spree-upgrade-5-to-6.
- Skillspree-workflowsUse when the user wants to run custom code inside a Spree 6 business flow — veto an add-to-cart, block checkout completion, enforce a purchase limit or B2B rule, add data to tax or promotion calculation, react inside the order-placement transaction, customize returns eligibility, or write a new multi-step operation with compensation and gateway calls. Common phrasings include "Spree.hooks.register", "workflow hook", "carts.add_item.validate", "carts.complete.before_finalize", "set_tax_line_context", "reject!", "Spree::Workflow", "step / external_step / on_flow_failure", "run_hooks", "halt!", "has_status", "add_status", "state machine replacement", "where do I put business logic", "step.spree_workflow", "trace a workflow". Covers services vs workflows, the three hook kinds, the hook catalog, writing your own workflow, statuses, instrumentation and testing. Reach for this BEFORE swapping a class via Spree.dependencies or decorating a model.