building-with-medusa — Claude Code skill: how it works and installs
Defines architecture standards and guardrails for Medusa backend development. Useful when designing custom modules, API routes, or multi-step workflows.
npx skills add medusajs/medusa-agent-skills --skill building-with-medusa -a claude-codeWhat building-with-medusa does
This skill enforces strict Medusa backend layering: module data operations connect to workflows, workflows run inside API routes, and routes serve client requests. Any database mutation must run inside a workflow step rather than directly calling a module service from an endpoint. It also restricts HTTP methods to GET, POST, and DELETE.
The guidelines cover six priority groups, including module isolation, type checking, and file layout. Medusa uses Zod v4 since release v2.14.0, so the skill mandates importing schemas from @medusajs/framework/zod with specific methods like z.email() and z.strictObject(). Composition functions for workflows must stay synchronous without async arrows or direct await calls.
Price handling has a strict rule: Medusa stores amounts as direct numbers like 49.99, not in cents. Multiplying by 100 on writes will silently corrupt pricing data. Before writing any code, the agent must inspect matching files in the reference/ directory.
What it helps with
- implement mutation workflows with step rollbacks
- validate admin or store requests with Zod v4
- configure cross-module entity links
- query linked module entities using
query.index()
Example prompts for the agent
- Create a custom loyalty module and link it to the customer entity.
- Implement a mutation workflow for order cancellations with rollbacks.
- Add an admin POST route that validates input using AuthenticatedMedusaRequest.
How to install building-with-medusa
1Skills CLI (Vercel)
npx skills add medusajs/medusa-agent-skills --skill building-with-medusa -a claude-code2Manually: put the files in place
~/.claude/skills/building-with-medusa/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/building-with-medusa/
1Skills CLI (Vercel)
npx skills add medusajs/medusa-agent-skills --skill building-with-medusa -a codex2Manually: put the files in place
.agents/skills/building-with-medusa/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add medusajs/medusa-agent-skills --skill building-with-medusa -a cursor2Manually: put the files in place
.cursor/skills/building-with-medusa/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install medusajs/medusa-agent-skills building-with-medusa2Manually: put the files in place
.github/skills/building-with-medusa/SKILL.md1Skills CLI (Vercel)
npx skills add medusajs/medusa-agent-skills --skill building-with-medusa -a gemini-cli2Platform CLI
gemini skills install https://github.com/medusajs/medusa-agent-skills --path plugins/medusa-dev/skills/building-with-medusaManually: put the files in place
.devin/skills/building-with-medusa/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add medusajs/medusa-agent-skills --skill building-with-medusa -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about building-with-medusa
How to install building-with-medusa in Claude Code?
Run npx skills add medusajs/medusa-agent-skills --skill building-with-medusa -a claude-code. Alternatively, copy the skill configuration into ~/.claude/skills/building-with-medusa/SKILL.md.
What does building-with-medusa do?
It provides architecture patterns and linting rules for Medusa backend development, preventing layer bypasses and incorrect query methods.
How does the skill handle currency amounts?
Medusa stores prices directly as numbers such as 49.99 rather than cents. The skill instructs agents never to multiply prices by 100 during saves or divide them when rendering.
