# Medusajs Medusa Medusa

> Writing Medusa Tutorials

- Skill: `tomevault-io/medusajs-medusa-medusa` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/medusajs-medusa-medusa`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/medusajs-medusa-medusa/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/medusajs-medusa-medusa

---


# Writing Medusa Tutorials

Guides an agent through creating a complete Medusa tutorial: building the feature in an example project, then writing the documentation.

## Two-Phase Approach

**Phase 1 — Build:** Gather requirements → plan with user → implement feature → add tests → confirm with user
**Phase 2 — Write:** Create step diagram → write per-step MD files → combine into final MDX → update sidebar → clean up

> **CRITICAL:** Never do both phases in one session. Complete Phase 1, get user confirmation, then reload this skill for Phase 2.

## Load Reference Files When Needed

> **Load at least one reference file before proceeding.**

| Task | Load |
|------|------|
| Starting Phase 1 (building) | `reference/building-phase.md` |
| Starting Phase 2 (writing) | `reference/writing-phase.md` + `reference/tutorial-conventions.md` + `reference/concept-definitions.md` |
| MDX patterns and components | `reference/tutorial-conventions.md` |
| Concept definitions (module, workflow, etc.) | `reference/concept-definitions.md` |

## Quick Reference

### File Locations

| Type | Content Path | Sidebar File |
|------|-------------|--------------|
| How-to tutorial | `www/apps/resources/app/how-to-tutorials/tutorials/{name}/page.mdx` | `www/apps/resources/sidebars/how-to-tutorials.mjs` |
| Integration guide | `www/apps/resources/app/integrations/guides/{name}/page.mdx` | `www/apps/resources/sidebars/integrations.mjs` |

### Development Skills to Load During Build

- Backend features → `medusa-dev:building-with-medusa`
- Admin UI → `medusa-dev:building-admin-dashboard-customizations`
- Storefront → `medusa-dev:building-storefronts`
- Third-party services → `context7` MCP or skills
- Medusa API questions → `mcp__medusa__ask_medusa_question`

## Common Mistakes

- [ ] Jumping straight to writing documentation without building the feature first
- [ ] Writing both phases in one session without user confirmation between them
- [ ] Writing Step 1 (Medusa installation) from scratch — use the pre-written template in `tutorial-conventions.md`
- [ ] Forgetting to update the sidebar after writing the tutorial MDX
- [ ] Leaving `_step-*.md` temp files after combining into final MDX
- [ ] Making tutorial code overly complex — tutorials are educational, keep it simple

---
> Source: [medusajs/medusa](https://github.com/medusajs/medusa) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-25 -->