spree/agent-skills — Agentic CLI guidance for Spree projects

Status: Complete Target: Spree 5.5 Depends on: none Author: Damian Legawiec ([email protected]) Last updated: 2026-06-12

Summary

spree/agent-skills is a standalone GitHub repository (github.com/spree/agent-skills) that ships agent-readable guidance for Spree Commerce projects: 25 Claude Code skills (model-invoked, progressive disclosure), a spree-expert subagent for multi-step investigations, two slash commands (/spree:doctor, /spree:audit-upgrade), two safety hooks (block destructive db commands, warn on hardcoded secrets), and an agents.md-spec AGENTS.md for cross-tool discovery.

Distribution uses the 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:

npx skills add spree/agent-skills

This installs into the user's project for whichever agent(s) they have configured — Claude Code, Codex, Cursor, GitHub Copilot, Cline, Aider, Zed, Windsurf, OpenCode, and 60+ others — using each tool's native file convention. Claude Code users who want the two safety hooks can additionally install via the plugin marketplace path (/plugin marketplace add spree/agent-skills → /plugin install spree@spree) which delivers the slash commands and hooks alongside the skills.

This is for Spree users, not monorepo contributors. Skills reference backend/, published gems, the @spree/cli Docker stack, and the public API surfaces — not the monorepo's server/ or SPREE_PATH workflows.

Key Decisions (do not deviate without discussion)

• Standalone repository at spree/agent-skills, not a package inside the monorepo. The skills repo evolves independently from gem releases — skill content changes when API surface or conventions shift, not in lockstep with spree-5.5.x tags. Matches Medusa's precedent (medusajs/medusa-agent-skills).
• Distribution channel is the skills CLI (npx skills add spree/agent-skills). Tool-agnostic, supports 70+ agentic CLIs out of the box, free, automatic listing at 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 slash commands and 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.
• 25 skills, one subagent, two commands, 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-storefront). The spree-dashboard skill (React admin extension) is held back until the React admin GAs with Spree 6.0 — shipping instructions for an unreleased admin would misroute 5.x users; it returns to the set at 6.0.
• 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.

Design Details

Standalone repo layout (github.com/spree/agent-skills)

agent-skills/
├── .claude-plugin/
│   └── plugin.json              # Claude Code plugin manifest (name: "spree", version, description)
├── agents/
│   └── spree-expert.md          # Subagent with YAML frontmatter (name, description, model?)
├── hooks/
│   ├── hooks.json               # PreToolUse:Bash, PostToolUse:Edit|Write|MultiEdit
│   ├── block_destructive_db.sh
│   └── warn_on_secrets.sh
├── skills/
│   └── <skill-name>/SKILL.md    # 25 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
└── .gitignore

No package.json, no src/, no TypeScript build, no dist/. Just content + manifests. Matches anthropics/skills convention.

The 25 skills

Distribution paths

Path 1 — npx skills add (canonical, all agents)

npx skills add spree/agent-skills

The skills CLI clones the repo, detects which agentic CLI(s) the user has installed (.claude/, .codex/, .cursor/, .clinerules/, etc.), and copies skill files into each tool's native location. Single command works for new and existing projects.

Sub-options the CLI supports:

• --list — preview without installing
• --skill <name> — install a subset
• --agent <name> — target a specific agent
• --global — install to ~/<agent>/skills/ instead of the project
• --all — install everything to all detected agents (CI-friendly)

Update later: npx skills update. List installed: npx skills list. Remove: npx skills remove.

Path 2 — Claude Code plugin (skills + subagent + hooks)

For Claude Code users who want the two safety hooks too:

/plugin marketplace add spree/agent-skills
/plugin install spree@spree

/plugin marketplace add registers spree/agent-skills as a plugin marketplace. /plugin install reads .claude-plugin/plugin.json and installs the plugin. Hooks resolve ${CLAUDE_PLUGIN_ROOT} to the cached plugin directory.

Users picking this path should not also run npx skills add — the two paths would install the same skills twice.

Optional follow-up: submit to anthropics/claude-plugins-community via https://platform.claude.com/plugins/submit so users can install via /plugin install spree@claude-community without registering our marketplace first.

Path 3 — Manual git clone + cp (offline / air-gapped)

git clone https://github.com/spree/agent-skills.git
mkdir -p .claude/skills .claude/agents
cp -R agent-skills/skills/* .claude/skills/
cp -R agent-skills/agents/* .claude/agents/

Skills and subagent work. Hooks don't (no ${CLAUDE_PLUGIN_ROOT} resolution).

create-spree-app integration

The scaffold does not bundle skills any more. Instead:

1. Removes the @spree/agent-skills workspace dep from packages/create-spree-app/package.json.

2. Removes src/skills.ts and the writeClaudeArtifacts(projectDir) call from src/scaffold.ts.

3. Adds a post-scaffold hint to the success message:

   textCopy

   Agent skills (optional)
     npx skills add spree/agent-skills
     # Adds 25 Spree skills to whichever AI agent(s) you use
     # (Claude Code, Codex, Cursor, Copilot, Cline, Aider, +60 others)
   

4. The scaffold's generated root AGENTS.md template includes the same hint so Codex/Aider/Zed users walking up from cwd find it.

Result: create-spree-app becomes simpler (no skill-copying code, one fewer dep), and skills update independently of the scaffold's release cadence. Users opt in to the latest skills via npx skills update whenever they want.

Cross-tool compatibility

The skills CLI handles per-tool delivery. Under the hood it places skill files where each tool expects:

Local testing

Before releasing, verify end-to-end via at least one of these:

1. claude --plugin-dir <path-to-local-clone> — fastest iteration for the plugin path. Skills, subagent, hooks all load; ${CLAUDE_PLUGIN_ROOT} resolves to the directory.

2. npx skills add <local-path> — verifies the skills CLI install path. The CLI supports local-path sources per its README:

   bashCopy

   cd /tmp/test-project
   npx skills add /Users/damian/github/agent-skills
   

3. npx skills add spree/agent-skills against the pushed repo — final verification. Run from a throwaway directory.

4. Codex/Cursor inside a clone of the repo — verifies AGENTS.md auto-discovery for non-Claude tools.

Release process

Lightweight — no npm publish, no changesets, no monorepo tagging coordination.

1. Make changes in github.com/spree/agent-skills. Open a PR. Merge.
2. Bump the version in .claude-plugin/plugin.json. Commit.
3. Tag the release commit: git tag v0.2.0 && git push origin v0.2.0. This is what Claude Code's plugin install resolves against; npx skills add always resolves to the default branch unless a tag is explicitly requested.
4. (Optional) Submit to community marketplaces: anthropics/claude-plugins-community for Claude Code; skills.sh auto-lists public GitHub repos with skills.

That's the whole cycle.

Migration Path

This is a new repository — no migration needed for users. Adoption is opt-in for existing Spree projects and recommended (but optional, via post-scaffold message) for new ones.

For monorepo contributors who had the packages/agent-skills/ workspace package during development: it's removed entirely. No replacement workspace package exists in spree/spree. Skill changes are PRs to github.com/spree/agent-skills instead.

For users who had a previous version of the skills installed (via create-spree-app scaffold's old behavior): run npx skills update to converge on the latest, or npx skills remove + npx skills add spree/agent-skills to do a clean reinstall.

Constraints on Current Work

For anyone modifying anything in github.com/spree/agent-skills:

• Skill content targets users, not contributors. Reference backend/, published gems, the @spree/cli Docker stack, public API surfaces. Never reference the monorepo's server/ directory or the SPREE_PATH environment variable — those are internal-only.
• YAML frontmatter on every SKILL.md must include name and description. The description is what Claude reads to decide whether to invoke the skill — make it specific and include common trigger phrasings.
• Cross-references between skills use the bare skill name in backticks: `spree-events-webhooks` skill. When renaming a skill, grep for all references and fix them.
• Bump .claude-plugin/plugin.json version on each release and tag the commit (git tag v<x.y.z>). Untagged releases force Claude Code to treat every commit as a version bump.
• No package.json, no build step. If a future feature needs build tooling (CSS-to-frontmatter conversion, schema validation, etc.), introduce it deliberately and re-evaluate this constraint — but don't add it casually.
• AGENTS.md is the single source of truth for cross-tool guidance. Don't add .cursorrules, codex.md, .clinerules/, or other per-tool adapter files. The skills CLI handles per-tool delivery; the source repo only needs the canonical formats.

For anyone modifying packages/create-spree-app/ in the Spree monorepo:

• Do not re-introduce the skill-copying code. The scaffold prints a hint pointing at npx skills add spree/agent-skills and that's it. If you find yourself wanting to bundle skills again, the answer is "no — bumping a single dep is harder than running one npx command."

Open Questions

• Submit to skills.sh proactively or wait for organic listing? Public GitHub repos with the right structure auto-appear over time. We can also submit at https://skills.sh/submit to expedite. Recommend submitting on 5.5 release for visibility.
• Submit to anthropics/claude-plugins-community? This makes /plugin install spree@claude-community work without users adding our marketplace first. Worth doing as a follow-up after 5.5 ships and we have user feedback.
• Versioning policy for the standalone repo. Semver per semver.org? Or calendar versioning (v2026.06)? Semver is the convention on skills.sh; recommend semver, starting at v0.1.0.
• CI for the repo. Should we wire up link-checking against spree/spree? Spell-check on skill content? Skill-content lint that verifies YAML frontmatter has the required fields? Out of scope for 5.5; track as a follow-up if drift becomes visible.
• Should the AGENTS.md template in create-spree-app be more elaborate? Currently it points users at npx skills add. Could also link to the Spree docs, common commands, etc. Probably yes — but that's a polish pass not a blocker.

References

• Standalone repo: github.com/spree/agent-skills
• skills CLI: github.com/vercel-labs/skills
• skills.sh registry: skills.sh
• agents.md spec: agents.md
• Claude Code plugins: https://code.claude.com/docs/en/plugins
• Claude Code plugin marketplaces: https://code.claude.com/docs/en/plugin-marketplaces
• Reference precedent — Medusa: medusajs/medusa-agent-skills
• Reference precedent — Anthropic: anthropics/skills
• Reference precedent — Vercel: vercel-labs/agent-skills
• Related: docs/plans/5.4-spree-starter-and-create-spree-app.md