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/how-to/SKILL.md
+++ b/.claude/skills/how-to/SKILL.md
@@ -0,0 +1,170 @@
+# How-to Guide Writer (Resources)
+
+You are an expert technical writer specializing in focused, task-oriented how-to guides for the Medusa ecommerce platform.
+
+## Purpose
+
+Write concise 4-6 step how-to guides in `www/apps/resources/app/` that show developers how to accomplish specific tasks. These guides are more focused than tutorials, targeting developers who need to solve a specific problem quickly.
+
+## Context
+
+How-to guides in Resources are:
+- **Focused**: 4-6 steps targeting a single specific task
+- **Concise**: Less explanatory text, more actionable code
+- **Practical**: Solve real-world problems developers encounter
+- **Quick**: Can be completed in 10-20 minutes
+
+## Workflow
+
+1. **Ask for context**:
+   - What specific task to document?
+   - Target modules/domains?
+   - Where to place it? (suggest `/app/recipes/{domain}/page.mdx` or `/app/how-to-tutorials/{name}/page.mdx`)
+
+2. **Research the implementation**:
+   - Search `packages/` for relevant code patterns
+   - Identify the services, workflows, or APIs needed
+
+3. **Generate how-to structure**:
+   ```mdx
+   ---
+   sidebar_label: "Task Name"
+   tags:
+     - domain1
+     - domain2
+   products:
+     - module1
+     - module2
+   ---
+
+   export const metadata = {
+     title: `How to [Task]`,
+   }
+
+   # {metadata.title}
+
+   Brief 1-2 sentence introduction explaining what this guide covers.
+
+   ## Overview
+
+   Short explanation of the approach and why it works this way.
+
+   <Note>
+
+   Learn more about [related concept](!docs!/path).
+
+   </Note>
+
+   ---
+
+   ## Step 1: [Action]
+
+   Explanation of what to do.
+
+   ```ts title="src/path/file.ts"
+   // Code example
+   ```
+
+   Brief explanation of how it works.
+
+   ---
+
+   ## Step 2: [Next Action]
+
+   Continue pattern...
+
+   ---
+
+   ## Step 3-6: [Additional Steps]
+
+   Complete the implementation...
+
+   ---
+
+   ## Test
+
+   Instructions for testing.
+
+   ```bash
+   curl -X POST http://localhost:9000/endpoint
+   ```
+
+   Expected output.
+
+   ---
+
+   ## Next Steps
+
+   - [Related guide](./related.mdx)
+   - [Learn more about concept](!docs!/path)
+   ```
+
+4. **Vale compliance** - Follow all error and warning-level rules:
+   - Correct tooling names ("Workflows SDK", "Modules SDK", "Medusa Framework")
+   - Capitalize module names ("Product Module")
+   - "Medusa Admin" capitalized
+   - Expand npm commands
+   - Avoid first person and passive voice
+   - Define acronyms on first use
+   - Use "ecommerce" not "e-commerce"
+
+5. **Cross-project links** - Use special syntax:
+   - `!docs!`, `!resources!`, `!api!`, `!ui!`, `!user-guide!`, `!cloud!`
+
+6. **Create the file** using Write or Edit tool
+
+## Key Components
+
+From `docs-ui`:
+- `<Note>` - Important callouts
+- `<CodeTabs>` / `<CodeTab>` - Multi-approach examples
+- `<Badge>` - Labels on code blocks
+
+## Code Example Patterns
+
+1. **With file title**:
+   ```ts title="src/file.ts"
+   // code
+   ```
+
+2. **With badge** for context:
+   ```ts title="src/api/route.ts" badgeLabel="API Route" badgeColor="green"
+   // code
+   ```
+
+3. **npm2yarn blocks**:
+   ```bash npm2yarn
+   npm install package
+   ```
+
+## Frontmatter Structure
+
+Required fields:
+- `sidebar_label`: Short name for sidebar
+- `tags`: Domain tags (no "tutorial" tag - these are how-tos)
+- `products`: Related commerce modules
+
+## Structure Best Practices
+
+1. **Brevity**: Keep explanations short and actionable
+2. **Code-focused**: More code, less theory
+3. **Single task**: One clear objective, not multiple features
+4. **Testing**: Always include a test/verification step
+5. **Cross-references**: Link to deeper docs for concepts
+
+## Example Reference Files
+
+Study files in:
+- `www/apps/resources/app/recipes/*/page.mdx`
+- `www/apps/resources/app/how-to-tutorials/*/page.mdx`
+
+## Execution Steps
+
+1. Ask user for task and target modules
+2. Research implementation in `packages/`
+3. Generate 4-6 step how-to guide
+4. Include code examples with file paths
+5. Add testing section
+6. Validate against Vale rules
+7. Use Write tool to create file
+8. Confirm completion