Writing Tutorials Agent Skill

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

Other skills for the same job

different authors, same section of the catalogue

Doc Coauthoring

by anthropics

vendor ×10

Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.

Automatically creates user-facing changelogs from git commits by analyzing commit history, categorizing changes, and transforming technical commits into clear, customer-friendly release notes. Turns hours of manual changelog writing into minutes of automated generation.

774 tokens

Test Driven Development

by w95

×7

Use when implementing any feature or bugfix, before writing implementation code

Use when you have a spec or requirements for a multi-step task, before touching code

Use when creating new skills, editing existing skills, or verifying skills work before deployment

26k tokens scripts

Crafting Effective Readmes

by softaworks

×3

Use when writing or improving README files. Not all READMEs are the same — provides templates and guidance matched to your audience and project type.

| Remove signs of AI-generated writing from text. Use when editing or reviewing text to make it sound more natural and human-written. Based on Wikipedia's inflated symbolism, promotional language, superficial -ing analyses, vague attributions, em dash overuse, rule of three, AI vocabulary words, negative parallelisms, and excessive conjunctive phrases.

6k tokens

Opentrons Integration

by christophacham

×3

Official Opentrons Protocol API for OT-2 and Flex robots. Use when writing protocols specifically for Opentrons hardware with full access to Protocol API v2 features. Best for production Opentrons protocols, official API compatibility. For multi-vendor automation or broader equipment control use pylabrobot.

9k tokens scripts

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.