medusa-store/.claude/skills/resources-doc/SKILL.md

# Resources Documentation Writer

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

## Purpose

Write general reference documentation in `www/apps/resources/app/` for commerce modules, infrastructure modules, integrations, and other technical references. This is the main skill for Resources documentation that doesn't fit into tutorials, how-tos, or recipes.

## Context

Resources documentation includes:
- **Commerce Modules** (`commerce-modules/`): Feature modules like Product, Order, Cart, Customer
- **Infrastructure Modules** (`infrastructure-modules/`): System modules like Cache, Event, File, Notification
- **Integrations** (`integrations/`): Third-party service integrations
- **Admin Components** (`admin-components/`): React components for extending Medusa Admin
- **References** (`references/`): Technical references and configurations
- **Tools** (`tools/`): CLI tools, utilities, SDKs

These are developer-focused reference docs that explain features, provide code examples, and link to detailed guides.

## Workflow

1. **Ask for context**:
   - What type of documentation? (commerce module / infrastructure module / integration / admin component / reference / tool)
   - Which specific feature or module?
   - What aspects to cover?

2. **Research the implementation**:
   - For modules: Search `packages/modules/{module}/` for services, data models, workflows
   - For admin components: Search `packages/admin/dashboard/src/components/` for React components
   - For tools: Search `packages/cli/` or relevant tool directories
   - Read service files to understand available methods and features

3. **Analyze existing patterns**:
   - Read 1-2 similar documentation pages in the same category
   - Note the structure and component usage
   - Check frontmatter requirements

4. **Generate documentation structure**:

   **For Commerce/Infrastructure Module Overview**:
   ```mdx
   ---
   generate_toc: true
   ---

   import { CodeTabs, CodeTab } from "docs-ui"

   export const metadata = {
     title: `{Module Name} Module`,
   }

   # {metadata.title}

   In this section of the documentation, you'll find resources to learn more about the {Module Name} Module and how to use it in your application.

   <Note title="Looking for no-code docs?">

   Refer to the [Medusa Admin User Guide](!user-guide!/path) to learn how to manage {feature} using the dashboard.

   </Note>

   Medusa has {feature} related features available out-of-the-box through the {Module Name} Module. A [module](!docs!/learn/fundamentals/modules) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this {Module Name} Module.

   <Note>

   Learn more about why modules are isolated in [this documentation](!docs!/learn/fundamentals/modules/isolation).

   </Note>

   ## {Module Name} Features

   - **[Feature 1](/references/module/models/ModelName)**: Description of the feature
   - **[Feature 2](./guides/guide-name/page.mdx)**: Description of the feature
   - **[Feature 3](../related-module/page.mdx)**: Description of the feature

   ---

   ## How to Use the {Module Name} Module

   In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](!docs!/learn/fundamentals/workflows), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.

   You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.

   For example:

   export const highlights = [
     ["12", "Modules.{MODULE}", "Resolve the module in a step."]
   ]

   ```ts title="src/workflows/example.ts" highlights={highlights}
   import {
     createWorkflow,
     WorkflowResponse,
     createStep,
     StepResponse,
   } from "@medusajs/framework/workflows-sdk"
   import { Modules } from "@medusajs/framework/utils"

   const exampleStep = createStep(
     "example-step",
     async ({}, { container }) => {
       const moduleService = container.resolve(Modules.{MODULE})

       // Use module service methods
       const result = await moduleService.someMethod({
         // parameters
       })

       return new StepResponse({ result }, result.id)
     },
     async (resultId, { container }) => {
       if (!resultId) {
         return
       }
       const moduleService = container.resolve(Modules.{MODULE})

       // Rollback logic
       await moduleService.deleteMethod([resultId])
     }
   )

   export const exampleWorkflow = createWorkflow(
     "example-workflow",
     () => {
       const { result } = exampleStep()

       return new WorkflowResponse({
         result,
       })
     }
   )
   ```

   In the example above, you create a custom workflow with a step that uses the {Module Name} Module's main service to perform operations.

   <Note>

   Learn more about workflows in the [Workflows documentation](!docs!/learn/fundamentals/workflows).

   </Note>

   You can also use the {Module Name} Module's service directly in other resources, such as API routes:

   ```ts title="src/api/custom/route.ts"
   import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
   import { Modules } from "@medusajs/framework/utils"

   export async function GET(
     req: MedusaRequest,
     res: MedusaResponse
   ) {
     const moduleService = req.scope.resolve(Modules.{MODULE})

     const items = await moduleService.listMethod()

     res.json({ items })
   }
   ```

   ---

   ## Guides

   <CardList items={[
     {
       href: "./guides/guide-1/page.mdx",
       title: "Guide 1 Title",
       text: "Description of what this guide covers"
     },
     {
       href: "./guides/guide-2/page.mdx",
       title: "Guide 2 Title",
       text: "Description of what this guide covers"
     }
   ]} />

   ---

   ## Data Models

   The {Module Name} Module defines the following data models:

   <CardList items={[
     {
       href: "/references/module/models/ModelName",
       title: "Model Name",
       text: "Description of the data model"
     }
   ]} />

   Learn more about data models and their properties in the [References](/references/module).

   ---

   ## Related Modules

   <CardList items={[
     {
       href: "../related-module/page.mdx",
       title: "Related Module",
       text: "How this module relates"
     }
   ]} />
   ```

   **For Feature/Concept Page**:
   ```mdx
   export const metadata = {
     title: `Feature Name`,
   }

   # {metadata.title}

   In this document, you'll learn about {feature} and how to use it.

   ## What is {Feature}?

   Explanation of the feature and its purpose.

   <Note>

   Learn more about [related concept](!docs!/path).

   </Note>

   ---

   ## How to Use {Feature}

   ### In a Workflow

   Example showing usage in a workflow:

   ```ts title="src/workflows/example.ts"
   // Workflow code example
   ```

   ### In an API Route

   Example showing usage in an API route:

   ```ts title="src/api/route.ts"
   // API route code example
   ```

   ---

   ## Example Use Cases

   ### Use Case 1

   Explanation and code example.

   ### Use Case 2

   Explanation and code example.

   ---

   ## Related Resources

   - [Related guide](./guides/page.mdx)
   - [Module reference](/references/module)
   - [Workflow documentation](!docs!/learn/fundamentals/workflows)
   ```

   **For Integration Documentation**:
   ```mdx
   export const metadata = {
     title: `{Service} Integration`,
   }

   # {metadata.title}

   In this document, you'll learn how to integrate {Service} with Medusa.

   ## Prerequisites

   - Active {Service} account
   - API credentials from {Service}
   - Medusa application installed

   ---

   ## Installation

   ```bash npm2yarn
   npm install medusa-{service}
   ```

   ---

   ## Configuration

   Add the integration to your `medusa-config.ts`:

   ```ts title="medusa-config.ts"
   export default defineConfig({
     modules: [
       {
         resolve: "medusa-{service}",
         options: {
           apiKey: process.env.SERVICE_API_KEY,
         },
       },
     ],
   })
   ```

   ---

   ## Usage

   ### In a Workflow

   Code example showing integration usage.

   ### Available Methods

   Description of available methods and their parameters.

   ---

   ## Testing

   Instructions for testing the integration.

   ---

   ## Related Resources

   - [{Service} Documentation](https://external-link)
   - [Module Development](!docs!/learn/fundamentals/modules)
   ```

5. **Vale compliance** - Follow all error and warning-level rules:
   - Correct tooling names: "Workflows SDK", "Modules SDK", "Medusa Framework"
   - Capitalize module names: "Product Module", "Commerce Module", "Infrastructure Module"
   - "Medusa Admin" always capitalized
   - Expand npm commands: `npm install` not `npm i`
   - Avoid first person and passive voice
   - Define acronyms on first use
   - Use "ecommerce" not "e-commerce"

6. **Cross-project links** - Use special syntax:
   - Main docs: `!docs!/learn/path`
   - User guide: `!user-guide!/path`
   - API reference: `!api!/admin` or `!api!/store`
   - Other resources: relative paths or `!resources!/path`

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

## Key Components

From `docs-ui`:
- `<CardList>` - Navigation cards for guides, models, related modules
- `<Note>` - Callout boxes (use `title` prop)
- `<CodeTabs>` / `<CodeTab>` - Multi-language/approach examples
- `<Table>` - Data tables for comparisons

## Frontmatter Structure

For overview pages:
- `generate_toc: true` - Auto-generate table of contents

For feature pages:
- Minimal frontmatter or none, just metadata export

## Code Example Patterns

1. **Workflow example with highlights**:
   ```mdx
   export const highlights = [
     ["12", "Modules.PRODUCT", "Explanation"]
   ]

   ```ts title="src/workflows/example.ts" highlights={highlights}
   // code
   ```
   ```

2. **API route example**:
   ```ts title="src/api/route.ts"
   import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
   // code
   ```

3. **Configuration example**:
   ```ts title="medusa-config.ts"
   export default defineConfig({
     // config
   })
   ```

## Documentation Structure by Type

**Module Overview**:
1. Introduction with User Guide link
2. Feature list with links
3. "How to Use" section with workflow and API examples
4. Guides section with CardList
5. Data Models section with CardList
6. Related Modules section

**Feature/Concept Page**:
1. Introduction
2. "What is X?" explanation
3. "How to Use X" with code examples
4. Example use cases
5. Related resources

**Integration Page**:
1. Introduction
2. Prerequisites
3. Installation
4. Configuration
5. Usage examples
6. Testing
7. Related resources

## Research Sources

When documenting features, research:
- **Modules**: `packages/modules/{module}/src/` for services and data models
- **Admin components**: `packages/admin/dashboard/src/components/` for React components
- **Workflows**: `packages/core/core-flows/src/{domain}/` for workflow patterns
- **Types**: `packages/core/types/src/` for interfaces and type definitions

## Example Reference Files

Study these files for patterns:
- Module overview: [www/apps/resources/app/commerce-modules/product/page.mdx](www/apps/resources/app/commerce-modules/product/page.mdx)
- Module list: [www/apps/resources/app/commerce-modules/page.mdx](www/apps/resources/app/commerce-modules/page.mdx)
- Feature pages: `www/apps/resources/app/commerce-modules/{module}/*/page.mdx`

## Execution Steps

1. Ask user for documentation type and feature
2. Research implementation in `packages/` directory
3. Read 1-2 similar documentation pages for patterns
4. Generate appropriate structure based on type
5. Include workflow and API route examples
6. Add CardList for navigation to guides and references
7. Include cross-project links to main docs and user guide
8. Validate against Vale rules
9. Use Write tool to create file
10. Confirm completion