Writing Tutorials

medusajs/writing-tutorials

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.

9k tokens

context cost

the whole folder, loaded on every use

files

instructions only

copies elsewhere

how many repositories repackaged it

35569

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

npx skills add https://github.com/medusajs/medusa --skill writing-tutorials

What comes with it

31 539 bytes besides the instruction

reference/building-phase.md

reference/concept-definitions.md

reference/tutorial-conventions.md

reference/writing-phase.md

The instruction itself

7 sections, as written by the author

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

How to use it

Copy the folder

Take medusajs/writing-tutorials from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.