Agent skill · mindrally
medusa-development
Best practices for building commerce applications with Medusa v2, the headless e-commerce framework. Use when defining Medusa data models, writing workflows and steps with the Workflow SDK, creating API routes or subscribers, building module services that extend MedusaService, throwing MedusaError, or customizing the Medusa admin dashboard.
What it needs
About 6k tokens when loaded.
What this skill does
Medusa Development Medusa is a headless commerce framework built around modules, data models, and workflows; almost every piece of business logic — from an API route to a scheduled job — should be expressed as a workflow made of discrete, composable steps. Workflow for Building a Medusa Feature 1. Define or extend the data model — Use the model utility from @medusajs/framework/utils to declare the module's data model(s) under src/modules/<module>/models/. 2. Write the module service — Create a service in src/modules/<module>/service.ts that extends MedusaService when the module has data models, exposing async methods for domain operations. 3. Register the module — Add the module to medusa-config.ts so Medusa's container can resolve it. 4. Build steps — Define each unit of work as a step with createStep from @medusajs/framework/workflows-sdk, including a compensation function for anything that needs to be undone on failure. 5. Compose the workflow — Wire steps together with createWorkflow, using transform for data shaping and when for conditional branches. 6. Expose the workflow — Call the workflow from an API route, a scheduled job, or a subscriber — never put business logic directly in the route/job/subscriber handler. 7. Read data with Query — Use Medusa's Query (req.scope.resolve("query") or the workflow-level useQueryGraphStep) to fetch data instead of calling module services directly for reads. General Rules Don't use type aliases when importing files — import types and values directly from their source module rather than re-exporting through a local alias. When throwing errors, always throw MedusaError (from @medusajs/framework/utils) instead of a plain Error, so the API layer can map it to the correct HTTP status and error code. Always use Query to retrieve data rather than calling a module's service methods directly for reads — Query understands module links and can join data across modules in one call. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills mindrally/medusa-development