writing-tutorials

name	writing-tutorials
description	Creates Medusa documentation tutorials in two phases: first builds the tutorial feature in an example project (with planning, coding, and tests), then writes the MDX documentation. Use when creating a new how-to tutorial or integration guide for the Medusa docs. Handles both feature implementation and documentation writing, but only one phase at a time.

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