building-with-medusa

The building-with-medusa skill is an essential development companion for engineers working within the Medusa ecosystem. It codifies the rigorous architectural requirements and coding standards necessary to build scalable, type-safe, and maintainable backend features. By enforcing a strict layering strategy—ensuring that business logic remains decoupled from HTTP interfaces and data access—this skill helps developers avoid common pitfalls such as layer bypassing, improper data modeling, or suboptimal cross-module communication.

• Enables rapid implementation of custom modules, data models, and complex workflows with built-in rollback capabilities.

• Provides immediate guidance on API route structure, middleware integration, and Zod-based request validation.

• Facilitates efficient data retrieval patterns using query.graph and query.index to maintain module isolation.

• Incorporates critical technical constraints, such as the Medusa price handling convention and mandatory use of workflows for state-mutating operations.

• Includes a comprehensive lookup mechanism for reference documentation covering authentication, module linking, and query configuration.

• Always trigger this skill when planning, researching, or coding any backend component including modules, workflows, API routes, or data models.

• Load the relevant reference files (e.g., custom-modules.md, workflows.md) as a prerequisite to implementation to ensure adherence to the latest SDK requirements.

• Use this skill to validate adherence to Medusa's required architectural layers: Module → Workflow → API Route → Frontend.

• The skill acts as a guardrail for type safety, ensuring developers use AuthenticatedMedusaRequest and proper Zod schema exports.

• Follow the specified priority categories for code organization, starting from architectural integrity down to file-level conventions.