chore: add writing tutorials skill (#15078)

Author: shahednasser

.claude/skills/writing-tutorials/SKILL.md

@@ -0,0 +1,52 @@
+---
+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

.claude/skills/writing-tutorials/reference/building-phase.md

@@ -0,0 +1,92 @@
+# Phase 1: Building the Tutorial Feature
+
+Follow these steps to build the tutorial's feature in the example project before writing any documentation.
+
+## Step 1 — Gather Requirements
+
+Ask the user the following before doing anything else:
+
+1. **Tutorial topic** — What feature or integration is being built? (e.g., "product reviews", "PayPal integration")
+2. **Tutorial type** — How-to tutorial or integration guide?
+3. **Example project path** — Where is the target Medusa example project? (e.g., `~/projects/my-medusa-app`)
+4. **Third-party services** — Are any external services involved? (e.g., PayPal, Segment, Stripe)
+5. **Scope** — Should the tutorial include Admin UI customizations? Storefront customizations?
+
+Do NOT proceed until all required information is collected.
+
+## Step 2 — Research & Plan
+
+Before writing any code:
+
+1. Load `medusa-dev:building-with-medusa` — required for all backend work
+   - Also load `medusa-dev:building-admin-dashboard-customizations` if admin UI is in scope
+   - Also load `medusa-dev:building-storefronts` if storefront is in scope
+2. Use `mcp__medusa__ask_medusa_question` for questions about Medusa APIs, modules, and patterns
+3. For integrations with third-party services: use `context7` MCP or skills to retrieve their documentation
+
+**Write a plan covering:**
+- Data models to create (custom module if needed)
+- Workflows and their steps
+- API routes (store and/or admin)
+- Admin UI widgets/pages (if applicable)
+- Storefront components/changes (if applicable)
+- Seed data or configuration needed
+
+> **CRITICAL:** Keep it simple. Tutorial code is for learning, not production. Avoid unnecessary abstractions, overly generic utilities, or complex patterns. One clear approach beats multiple flexible ones.
+
+**Present the plan to the user and get explicit approval before writing any code.**
+
+## Step 3 — Build the Feature
+
+Follow the approved plan. Always follow the architecture layer order:
+
+```
+Custom Module (data models + CRUD)
+  ↓
+Workflow (business logic, mutations)
+  ↓
+API Route (HTTP interface)
+  ↓
+Admin UI / Storefront
+```
+
+**Useful commands:**
+- Generate migration: `/medusa-dev:db-generate <module-name>`
+- Run migrations: `/medusa-dev:db-migrate`
+- Create admin user: `/medusa-dev:new-user <email> <password>`
+
+Load reference files from `medusa-dev:building-with-medusa` for each component as you build it.
+
+## Step 4 — Add Tests
+
+Write tests to validate the implementation:
+
+- **Workflow steps** — Unit tests for each step's main logic
+- **API routes** — Integration tests covering success and error cases
+- **Custom module service methods** — Unit tests for any non-trivial service logic
+
+Place tests in:
+- `integration-tests/` for API/integration tests
+- `src/**/__tests__/` for unit tests
+
+Keep tests simple and focused on verifying the feature works as expected. These tests also serve as examples for tutorial readers.
+
+## Step 5 - Validate Implementation
+
+Before finishing up, make sure that:
+
+1. Build passes: `yarn build`
+2. Integration and unit tests pass
+
+Fix all issues before wrapping up.
+
+## Step 6 — Wrap Up
+
+1. Tell the user to test the feature manually:
+   - Start the Medusa app and test relevant API routes
+   - Verify in the Admin UI (if applicable)
+   - Verify in the Storefront (if applicable)
+2. Ask the user: **"Does everything look good? Let me know when you're ready to write the tutorial documentation."**
+3. Once the user confirms, instruct them: **"Reload `/writing-tutorials` and I'll help you write the documentation."**
+
+> **IMPORTANT:** Do not start writing documentation until the user explicitly confirms the build is complete and working.