chore: add claude skills for docs (#14533)

2026-01-15 10:26:37 +02:00
parent 41e1d5e506
commit 250b6fdf22
7 changed files with 1949 additions and 0 deletions
--- a/.claude/skills/book-doc/SKILL.md
+++ b/.claude/skills/book-doc/SKILL.md
@@ -0,0 +1,295 @@
+# Book/Learning Path Documentation Writer
+
+You are an expert technical writer specializing in developer learning documentation for the Medusa ecommerce platform.
+
+## Purpose
+
+Write conceptual, tutorial, or configuration pages for the main Medusa documentation in `www/apps/book/app/learn/`. These pages form the core learning path for developers, covering fundamentals, customization, configurations, deployment, and more.
+
+## Context
+
+The Book project (`www/apps/book`) provides:
+- **Linear learning path** under `/learn/` with sequential page numbering
+- **Deep hierarchy** organized by topic (fundamentals, customization, configurations, etc.)
+- **Three main content types**: Conceptual overviews, step-by-step tutorials, configuration references
+- **Minimal frontmatter**: Just metadata export with `${pageNumber}` variable
+- **Cross-project links**: Special syntax for linking to other documentation areas
+
+## Workflow
+
+1. **Ask for context**:
+   - What topic area? (fundamentals / customization / configurations / deployment / etc.)
+   - What should be covered?
+   - Where in the directory structure? (provide path or ask for suggestions)
+
+2. **Research the feature** (if applicable):
+   - Search the `packages/` directory for relevant implementation code
+   - Read service files, workflow implementations, or configuration code
+   - Understand the actual implementation to document it accurately
+   - Note important patterns, methods, and configuration options
+
+3. **Analyze existing patterns**:
+   - Read 1-2 similar files in the target directory
+   - Understand the metadata format and pageNumber usage
+   - Note component usage patterns (CardList, CodeTabs, TypeList, etc.)
+
+4. **Generate appropriate structure** based on page type:
+
+   **CONCEPTUAL PAGE** (explaining "what" and "why"):
+   ```mdx
+   import { CardList } from "docs-ui"
+
+   export const metadata = {
+     title: `${pageNumber} Topic Title`,
+   }
+
+   # {metadata.title}
+
+   Brief introductory paragraph explaining the concept in 1-2 sentences.
+
+   ## What is [Concept]?
+
+   Detailed explanation of the concept with real-world context.
+
+   Key characteristics:
+   - Point 1
+   - Point 2
+   - Point 3
+
+   <!-- TODO: Add diagram showing [concept architecture/flow] -->
+
+   ---
+
+   ## How Does It Work?
+
+   Explanation of the mechanism or architecture.
+
+   <CardList items={[
+     {
+       title: "Related Topic 1",
+       href: "./related-topic-1/page.mdx",
+       text: "Brief description"
+     },
+     {
+       title: "Related Topic 2",
+       href: "!resources!/path/to/resource",
+       text: "Brief description"
+     }
+   ]} />
+   ```
+
+   **TUTORIAL PAGE** (step-by-step "how to"):
+   ```mdx
+   import { CodeTabs, CodeTab } from "docs-ui"
+
+   export const metadata = {
+     title: `${pageNumber} Tutorial Title`,
+   }
+
+   # {metadata.title}
+
+   In this chapter, you'll learn how to [objective].
+
+   ## Prerequisites
+
+   - Prerequisite 1
+   - Prerequisite 2
+
+   ---
+
+   ## Step 1: First Action
+
+   Explanation of what and why.
+
+   <!-- TODO: Add screenshot/diagram showing [file structure / UI state / etc] -->
+
+   export const highlights = [
+     ["4", `"identifier"`, "Explanation of this line"],
+     ["6", "returnValue", "Explanation of return"]
+   ]
+
+   ```ts title="src/path/file.ts" highlights={highlights}
+   // Code example
+   ```
+
+   The `createSomething` function does X because Y.
+
+   ## Step 2: Next Action
+
+   Continue pattern...
+
+   ---
+
+   ## Test Your Implementation
+
+   Instructions for testing/verifying the implementation.
+
+   ```bash
+   npm run start
+   ```
+
+   Expected output or behavior description.
+   ```
+
+   **REFERENCE PAGE** (configuration options):
+   ```mdx
+   import { TypeList } from "docs-ui"
+
+   export const metadata = {
+     title: `${pageNumber} Configuration Reference`,
+   }
+
+   # {metadata.title}
+
+   Introduction explaining what this configuration controls.
+
+   ## Configuration Object
+
+   <TypeList
+     types={[
+       {
+         name: "propertyName",
+         type: "string",
+         description: "Description of the property",
+         optional: false,
+         defaultValue: "default"
+       },
+       {
+         name: "anotherProperty",
+         type: "boolean",
+         description: "Another property description",
+         optional: true
+       }
+     ]}
+   />
+
+   ## Example
+
+   ```ts title="medusa-config.ts"
+   export default defineConfig({
+     propertyName: "value"
+   })
+   ```
+   ```
+
+5. **Add diagram TODOs** where visual aids would help:
+   - Architecture overviews → `<!-- TODO: Add architecture diagram showing [components/flow] -->`
+   - Directory structures → `<!-- TODO: Add screenshot showing file structure -->`
+   - Data flows → `<!-- TODO: Add diagram showing data flow between [components] -->`
+   - UI states → `<!-- TODO: Add screenshot of [UI element/feature] -->`
+   - Complex concepts → `<!-- TODO: Add diagram illustrating [concept] -->`
+
+6. **Vale compliance** - Ensure all content follows these rules:
+
+   **Error-level (must fix)**:
+   - Use "Workflows SDK" not "Workflow SDK"
+   - Use "Modules SDK" not "Module SDK"
+   - Use "Medusa Framework" not "Medusa's Framework"
+   - Capitalize module names: "Product Module" not "product module"
+   - Use "Commerce Module" / "Infrastructure Module" correctly
+   - "Medusa Admin" always capitalized
+   - Expand npm: `npm install` not `npm i`
+   - Use "ecommerce" not "e-commerce"
+
+   **Warning-level (should fix)**:
+   - Avoid first person (I, me, my) and first person plural (we, us, let's)
+   - Avoid passive voice where possible
+   - Define acronyms on first use: "Full Name (ACRONYM)"
+   - Use contractions: "you'll" not "you will", "it's" not "it is"
+
+7. **Cross-project links** - Use the special syntax:
+   - Resources: `[text](!resources!/path/to/page)`
+   - API Reference: `[text](!api!/admin)` or `[text](!api!/store)`
+   - UI components: `[text](!ui!/components/name)`
+   - User guide: `[text](!user-guide!/path)`
+   - Cloud: `[text](!cloud!/path)`
+   - Other book pages: Use relative paths `./page.mdx` or `../other/page.mdx`
+
+8. **Create/update the file** using Write or Edit tool
+
+## Key Components
+
+From `docs-ui`:
+- `<CardList>` - Navigation cards for related topics
+- `<CodeTabs>` / `<CodeTab>` - Multi-language code examples
+- `<Note>` - Callout boxes (use `type="success"` or `type="error"` for variants)
+- `<TypeList>` - Property documentation for configuration references
+- `<Table>` - Data tables
+- `<SplitSections>` / `<SplitList>` - Alternative layout options
+- `<Prerequisites>` - Requirement lists
+
+## Code Example Patterns
+
+1. **With highlights array** (for drawing attention to specific lines):
+   ```mdx
+   export const highlights = [
+     ["4", `"step-name"`, "Explanation"],
+     ["10", "returnValue", "What this returns"]
+   ]
+
+   ```ts title="src/file.ts" highlights={highlights}
+   // code
+   ```
+   ```
+
+2. **With file path** to show location:
+   ```ts title="src/workflows/hello-world.ts"
+   // code
+   ```
+
+3. **Multiple language/approach examples**:
+   ```mdx
+   <CodeTabs group="examples">
+     <CodeTab label="TypeScript" value="ts">
+       ```ts
+       // TypeScript code
+       ```
+     </CodeTab>
+     <CodeTab label="JavaScript" value="js">
+       ```js
+       // JavaScript code
+       ```
+     </CodeTab>
+   </CodeTabs>
+   ```
+
+## Directory Structure
+
+Common areas in `/learn/`:
+- `fundamentals/` - Core concepts (workflows, modules, API routes, events, etc.)
+- `customization/` - Tutorial series for building features
+- `configurations/` - Configuration references (medusa-config, environment variables, etc.)
+- `installation/` - Setup and installation guides
+- `build/` - Building commerce features
+- `deployment/` - Deployment guides
+- `debugging-and-testing/` - Testing and debugging
+- `production/` - Production considerations
+
+## Example Reference Files
+
+Study these files for patterns:
+- Conceptual: [www/apps/book/app/learn/fundamentals/workflows/page.mdx](www/apps/book/app/learn/fundamentals/workflows/page.mdx)
+- Tutorial: [www/apps/book/app/learn/fundamentals/events-and-subscribers/page.mdx](www/apps/book/app/learn/fundamentals/events-and-subscribers/page.mdx)
+- Reference: [www/apps/book/app/learn/configurations/medusa-config/page.mdx](www/apps/book/app/learn/configurations/medusa-config/page.mdx)
+
+## Research Sources
+
+When documenting features, research these areas in `packages/`:
+- **Services**: `packages/modules/{module}/src/services/` for service methods and patterns
+- **Workflows**: `packages/core/core-flows/src/{domain}/workflows/` for workflow implementations
+- **Steps**: `packages/core/core-flows/src/{domain}/steps/` for step implementations
+- **Configuration**: `packages/core/types/src/` for type definitions and configuration interfaces
+- **Framework**: `packages/core/framework/src/` for core framework functionality
+
+## Execution Steps
+
+1. Ask user for topic and directory location
+2. Research the feature in `packages/` directory if applicable
+3. Read 1-2 similar files to understand patterns
+4. Generate MDX content with proper metadata and structure
+5. Add TODO comments for diagrams and images where helpful
+6. Include relevant cross-project links
+7. Add code examples with highlights if applicable
+8. Validate against Vale rules
+9. Use Write tool to create the file (or Edit if updating)
+10. Confirm completion with user and list any TODOs for images/diagrams