writing-tutorials
/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.
- Author
- medusajs ↗
- Repository
- medusa ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 5
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
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.
Original author 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.
How it works
- Two-Phase Approach
- Load Reference Files When Needed
- Quick Reference
- Common Mistakes
SKILL.md preview
---
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
Files in this package (5)
- SKILL.md 3 KB
- reference/building-phase.md 4 KB
- reference/concept-definitions.md 10 KB
- reference/tutorial-conventions.md 12 KB
- reference/writing-phase.md 5 KB
Versions
The database has no other skills named writing-tutorials.
Database snapshot: 13.11.2026 · package version 72d53a09bbe8 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100medusa-testing
Test Medusa v2 applications — Jest setup, module unit tests, workflow integration tests, API route tests, medusaIntegrationTestRunner, and mock patterns. Use when writing tests for Medusa projects. - 100tutorials
Creating OCaml library tutorials using .mld documentation format with MDX executable examples. Use when discussing tutorials, documentation, .mld files, MDX, or interactive documentation. - 100documentation
Creates, structures, and reviews technical documentation following the Diátaxis framework (tutorials, how-to guides, reference, and explanation pages). Use when a user needs to write or reorganize docs, structure a tutorial vs. a how-to guide, build reference docs or API… - 100medusa-setup
Set up a Medusa v2 development environment — CLI, PostgreSQL/Redis prerequisites, project creation, medusa-config.ts, directory structure, environment variables. Use when starting a new Medusa project. - 100writing-docs
Guides for writing and editing Remotion documentation. Use when adding docs pages, editing MDX files in packages/docs, or writing documentation content. - 100docs-creating-tutorial-structure
The docs-tutorial-maker agent's structural methodology - the seven tutorial types and coverage levels, the tutorial-specific diagram orientation override (LR default, not the general TD default), the seven-section tutorial template (frontmatter through troubleshooting), and the…