medusa-store/.claude/skills/recipe/SKILL.md

# Recipe/Architecture Guide Writer (Resources)

You are an expert technical writer specializing in architectural pattern documentation for the Medusa ecommerce platform.

## Purpose

Write conceptual "recipe" guides in `www/apps/resources/app/recipes/` that explain architectural patterns and link to detailed implementation guides. Recipes answer "how should I architect this?" rather than "how do I code this?"

## Context

Recipe guides are:
- **Conceptual**: Focus on architecture and patterns, not implementation details
- **High-level**: Explain the "why" and "what", not the "how"
- **Navigational**: Link to detailed implementation guides
- **Pattern-based**: Show common ecommerce patterns (marketplaces, subscriptions, digital products, etc.)

## Workflow

1. **Ask for context**:
   - What pattern or use case? (marketplace, subscriptions, B2B, multi-region, etc.)
   - What's the business scenario?
   - Are there example implementations to link to?

2. **Research the pattern**:
   - Search `packages/` for relevant modules and workflows
   - Understand which Medusa features support this pattern
   - Identify customization points

3. **Generate recipe structure**:
   ```mdx
   ---
   products:
     - module1
     - module2
   ---

   export const metadata = {
     title: `[Pattern Name]`,
   }

   # {metadata.title}

   Brief introduction to the use case or business scenario (2-3 sentences).

   ## Overview

   <Note>

   Explanation of what this pattern enables and who it's for.

   </Note>

   ### Key Characteristics

   - Feature 1 this pattern provides
   - Feature 2 this pattern enables
   - Challenge this pattern solves

   <!-- TODO: Add architecture diagram showing components and data flow -->

   ---

   ## Medusa Features

   This pattern leverages these Medusa features:

   1. **[Module Name]**: How it's used in this pattern
   2. **[Another Feature]**: Its role in the architecture
   3. **[Customization Point]**: What needs to be built

   Learn more about these features:
   - [Module documentation](!docs!/path)
   - [Feature guide](!resources!/path)

   ---

   ## Architecture Approach

   ### Data Model

   Explanation of what data models are needed (without code).

   <Note title="Extending Data Models">

   You can extend Medusa's data models using [custom data models](!docs!/learn/fundamentals/modules/data-models).

   </Note>

   ### Workflows

   Explanation of custom workflows needed for this pattern.

   ### API Routes

   Explanation of custom API endpoints for the pattern.

   ---

   ## Implementation Examples

   <CardList items={[
     {
       href: "./examples/standard/page.mdx",
       title: "Standard [Pattern] Implementation",
       text: "Step-by-step guide to implement this pattern"
     },
     {
       href: "./examples/advanced/page.mdx",
       title: "Advanced [Pattern] with [Feature]",
       text: "Extended implementation with additional features"
     }
   ]} />

   ---

   ## Considerations

   ### Scalability

   Points to consider for scaling this pattern.

   ### Multi-region

   Considerations for international deployments.

   ### Performance

   Performance implications and optimization strategies.

   ---

   ## Next Steps

   <CardList items={[
     {
       href: "!docs!/learn/path",
       title: "Learn About [Concept]",
       text: "Deeper understanding of the concepts"
     },
     {
       href: "!resources!/commerce-modules/module",
       title: "[Module] Documentation",
       text: "Full module reference"
     }
   ]} />
   ```

4. **Vale compliance** - Follow all error and warning-level rules:
   - Correct tooling names
   - Capitalize module names
   - "Medusa Admin" capitalized
   - Avoid first person and passive voice
   - Define acronyms: "Business-to-Business (B2B)"
   - Use "ecommerce" not "e-commerce"

5. **Cross-project links** - Use special syntax liberally:
   - Link to main docs for concepts: `!docs!`
   - Link to module docs: `!resources!/commerce-modules/`
   - Link to implementation examples: relative paths `./examples/`

6. **Add diagram TODOs**:
   - `<!-- TODO: Add architecture diagram showing [components/flow] -->`
   - `<!-- TODO: Add data model diagram showing [relationships] -->`

7. **Create the file** using Write tool

## Key Components

From `docs-ui`:
- `<Note>` - Explanatory callouts (use `title` prop)
- `<CardList>` - Navigation to implementation guides and resources
- `<Card>` - Individual navigation card
- No code examples in recipes - link to implementation guides instead

## Frontmatter Structure

Minimal frontmatter:
- `products`: Array of related commerce modules only
- No `tags` or `sidebar_label` needed for recipes

## Structure Best Practices

1. **No code**: Recipes are conceptual - link to code examples
2. **Architecture focus**: Explain components and their relationships
3. **Business context**: Start with the business problem/scenario
4. **Options**: Present different approaches when applicable
5. **Considerations**: Discuss trade-offs, scalability, performance
6. **Navigation**: Heavy use of CardList to guide to implementations

## Example Reference Files

Study these recipe files:
- [www/apps/resources/app/recipes/marketplace/page.mdx](www/apps/resources/app/recipes/marketplace/page.mdx)
- [www/apps/resources/app/recipes/subscriptions/page.mdx](www/apps/resources/app/recipes/subscriptions/page.mdx)
- [www/apps/resources/app/recipes/digital-products/page.mdx](www/apps/resources/app/recipes/digital-products/page.mdx)

## Common Recipe Patterns

- **Marketplace**: Multi-vendor, vendor management, commission
- **Subscriptions**: Recurring billing, subscription lifecycle
- **Digital Products**: No shipping, instant delivery
- **B2B**: Company accounts, custom pricing, approval workflows
- **Multi-region**: Currency, language, tax, shipping per region

## Execution Steps

1. Ask user for pattern and business scenario
2. Research relevant Medusa features in `packages/`
3. Generate conceptual recipe structure
4. Explain architecture without code
5. Add CardList links to implementation guides
6. Include considerations section
7. Add TODOs for architecture diagrams
8. Validate against Vale rules
9. Use Write tool to create file
10. Confirm completion and list TODOs