# building-with-medusa

Defines architecture standards and guardrails for Medusa backend development. Useful when designing custom modules, API routes, or multi-step workflows.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 4600 installs · ★ 235
- Author: medusajs
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/medusajs/medusa-agent-skills/tree/HEAD/plugins/medusa-dev/skills/building-with-medusa/SKILL.md
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/skills/building-with-medusa

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add medusajs/medusa-agent-skills --skill building-with-medusa -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/building-with-medusa/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/building-with-medusa/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add medusajs/medusa-agent-skills --skill building-with-medusa -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/building-with-medusa/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add medusajs/medusa-agent-skills --skill building-with-medusa -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/building-with-medusa/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install medusajs/medusa-agent-skills building-with-medusa
```

2. **Manually: put the files in place**
- File: `.github/skills/building-with-medusa/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add medusajs/medusa-agent-skills --skill building-with-medusa -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/medusajs/medusa-agent-skills --path plugins/medusa-dev/skills/building-with-medusa
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/building-with-medusa/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add medusajs/medusa-agent-skills --skill building-with-medusa -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/medusajs/medusa-agent-skills/tree/HEAD/plugins/medusa-dev/skills/building-with-medusa/SKILL.md

## When to use it
- 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
- 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.

## Similar
- [zod-validation-utilities](https://affpapa.org/en/nevibecode/skills/zod-validation-utilities.md) — skill · 3800 installs
- [hono-api-scaffolder](https://affpapa.org/en/nevibecode/skills/hono-api-scaffolder.md) — skill · 1600 installs
- [express-typescript](https://affpapa.org/en/nevibecode/skills/express-typescript.md) — skill · 1400 installs
- [zod](https://affpapa.org/en/nevibecode/skills/bobmatnyc-zod.md) — skill · 887 installs
- [hono-typescript](https://affpapa.org/en/nevibecode/skills/hono-typescript.md) — skill · 819 installs
- [bun-hono-integration](https://affpapa.org/en/nevibecode/skills/bun-hono-integration.md) — skill · 452 installs

From the same set: [medusajs/medusa-agent-skills](https://affpapa.org/en/nevibecode/by/medusajs/medusa-agent-skills.md) — 11 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md