1---2name: medusajs-medusa-medusa3description: Writing Medusa Tutorials4---56# Writing Medusa Tutorials78Guides an agent through creating a complete Medusa tutorial: building the feature in an example project, then writing the documentation.910## Two-Phase Approach1112**Phase 1 — Build:** Gather requirements → plan with user → implement feature → add tests → confirm with user13**Phase 2 — Write:** Create step diagram → write per-step MD files → combine into final MDX → update sidebar → clean up1415> **CRITICAL:** Never do both phases in one session. Complete Phase 1, get user confirmation, then reload this skill for Phase 2.1617## Load Reference Files When Needed1819> **Load at least one reference file before proceeding.**2021| Task | Load |22|------|------|23| Starting Phase 1 (building) | `reference/building-phase.md` |24| Starting Phase 2 (writing) | `reference/writing-phase.md` + `reference/tutorial-conventions.md` + `reference/concept-definitions.md` |25| MDX patterns and components | `reference/tutorial-conventions.md` |26| Concept definitions (module, workflow, etc.) | `reference/concept-definitions.md` |2728## Quick Reference2930### File Locations3132| Type | Content Path | Sidebar File |33|------|-------------|--------------|34| How-to tutorial | `www/apps/resources/app/how-to-tutorials/tutorials/{name}/page.mdx` | `www/apps/resources/sidebars/how-to-tutorials.mjs` |35| Integration guide | `www/apps/resources/app/integrations/guides/{name}/page.mdx` | `www/apps/resources/sidebars/integrations.mjs` |3637### Development Skills to Load During Build3839- Backend features → `medusa-dev:building-with-medusa`40- Admin UI → `medusa-dev:building-admin-dashboard-customizations`41- Storefront → `medusa-dev:building-storefronts`42- Third-party services → `context7` MCP or skills43- Medusa API questions → `mcp__medusa__ask_medusa_question`4445## Common Mistakes4647- [ ] Jumping straight to writing documentation without building the feature first48- [ ] Writing both phases in one session without user confirmation between them49- [ ] Writing Step 1 (Medusa installation) from scratch — use the pre-written template in `tutorial-conventions.md`50- [ ] Forgetting to update the sidebar after writing the tutorial MDX51- [ ] Leaving `_step-*.md` temp files after combining into final MDX52- [ ] Making tutorial code overly complex — tutorials are educational, keep it simple5354---55> Source: [medusajs/medusa](https://github.com/medusajs/medusa) — distributed by [TomeVault](https://tomevault.io).56<!-- tomevault:4.0:skill_md:2026-06-25 -->
Run npx skillmds@latest add tomevault-io/medusajs-medusa-medusa in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Writing Medusa Tutorials It is listed under Coding & Dev Tools on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
tomevault-io (@tomevault-io) published this skill. Their other Agent Skills are listed on their SkillMD profile.