Skip to content

armgit / spree

Public Imported from GitHub
0

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.

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.md
index 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:
```text
Agent 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)
```