npx claudepluginhub adaptive-machines/medusa-agent-skills --plugin ecommerce-storefrontThis skill uses the workspace's default tool permissions.
Comprehensive guidance for building modern, high-converting ecommerce storefronts covering UI/UX patterns, component design, layout structures, SEO optimization, and mobile responsiveness.
reference/components/breadcrumbs.mdreference/components/cart-popup.mdreference/components/country-selector.mdreference/components/footer.mdreference/components/hero.mdreference/components/megamenu.mdreference/components/navbar.mdreference/components/popups.mdreference/components/product-card.mdreference/components/product-reviews.mdreference/components/product-slider.mdreference/components/search.mdreference/connecting-to-backend.mdreference/design.mdreference/features/promotions.mdreference/features/wishlist.mdreference/layouts/account.mdreference/layouts/cart.mdreference/layouts/checkout.mdreference/layouts/home-page.mdGuides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Generates original PNG/PDF visual art via design philosophy manifestos for posters, graphics, and static designs on user request.
Comprehensive guidance for building modern, high-converting ecommerce storefronts covering UI/UX patterns, component design, layout structures, SEO optimization, and mobile responsiveness.
ALWAYS load this skill when working on ANY storefront task:
Example prompts that should trigger this skill:
⚠️ ALWAYS load reference/design.md BEFORE creating ANY UI component
Load these references based on what you're implementing:
reference/design.md first to discover user preferencesreference/connecting-to-backend.md firstreference/medusa.md for SDK setup, pricing, regions, and Medusa patternsreference/components/navbar.md, reference/components/hero.md, reference/components/footer.md, and reference/layouts/home-page.mdreference/components/navbar.md and optionally reference/components/megamenu.mdreference/layouts/product-listing.md firstreference/layouts/product-details.md firstreference/layouts/checkout.md firstreference/seo.md firstreference/mobile-responsiveness.md firstMinimum requirement: Load at least 1-2 reference files relevant to your specific task before implementing.
IMPORTANT: If you create a plan for implementing storefront features, include the following in your plan:
When implementing each component, page, layout, or feature in the plan:
Example plan structure:
Task 1: Implement Navigation
- Load reference/components/navbar.md
- Follow patterns from navbar.md (dynamic category fetching, cart visibility, etc.)
- Refer to skill for common mistakes (e.g., hardcoding categories)
Task 2: Implement Product Listing Page
- Load reference/layouts/product-listing.md
- Follow pagination/filtering patterns from product-listing.md
- Use reference/components/product-card.md for product grid items
- Check skill for backend integration guidance
Task 3: Implement Checkout Flow
- Load reference/layouts/checkout.md
- Load reference/medusa.md for Medusa payment integration
- Follow component architecture recommendations (separate step components)
- Refer to skill for payment method fetching requirements
Why this matters:
aria-live="polite" - Screen readers won't announce without itenv(safe-area-inset-bottom) - iOS home indicator will cut off purchase buttons otherwiseloading="lazy" to product images below fold - Don't rely on browser defaultsYOU MUST FOLLOW THIS EXACT WORKFLOW BEFORE WRITING CODE THAT CONNECTS TO BACKEND:
Step 1: PAUSE - Do NOT write code yet
Step 2: QUERY the documentation or MCP server
Step 3: VERIFY what you found
sdk.store.cart.methodName(params)"Step 4: ONLY THEN write the code
Step 5: CHECK for TypeScript errors
THIS IS NOT OPTIONAL - THIS IS MANDATORY ERROR PREVENTION
It is a CRITICAL ERROR to:
For Medusa specifically:
reference/medusa.md for Medusa-specific patterns (regions, pricing, etc.)/products/[handle] or /products/$handle, NOT /products/shirt.tsx/categories/[handle] or /categories/$handle, NOT /categories/women.tsxapp/products/[handle]/page.tsx or app/products/[id]/page.tsxpages/products/[handle].tsxroutes/products/[handle]/+page.svelteroutes/products/$handle.tsxroutes/products.$handle.tsxWhen you need to choose between implementation patterns, load the relevant reference file:
reference/layouts/checkout.mdreference/components/navbar.md and reference/components/megamenu.mdreference/layouts/product-listing.mdreference/components/search.mdreference/mobile-responsiveness.mdreference/layouts/product-details.mdreference/components/cart-popup.md and reference/layouts/cart.mdreference/layouts/product-details.md and reference/layouts/checkout.mdEach reference file contains decision frameworks with specific criteria to help you choose the right pattern for your context.
reference/connecting-to-backend.md - Framework detection, API setup, backend integration patterns
reference/medusa.md - Medusa SDK integration, pricing, regions, TypeScript types
reference/design.md - User preferences, brand identity, design systems
reference/seo.md - Meta tags, structured data, Core Web Vitals
reference/mobile-responsiveness.md - Mobile-first design, responsive breakpoints, touch interactions
reference/components/navbar.md - Desktop/mobile navigation, logo, menu, cart icon, load for ALL pages
reference/components/megamenu.md - Category organization, featured products, mobile alternatives
reference/components/cart-popup.md - Add-to-cart feedback, mini cart display
reference/components/country-selector.md - Country/region selection, currency, pricing, Medusa regions
reference/components/breadcrumbs.md - Category hierarchy, structured data markup
reference/components/search.md - Search input, autocomplete, results, filters
reference/components/product-reviews.md - Review display, rating aggregation, submission
reference/components/hero.md - Hero layouts, CTA placement, image optimization
reference/components/popups.md - Newsletter signup, discount popups, exit-intent
reference/components/footer.md - Content organization, navigation, social media, load for ALL pages
reference/components/product-card.md - Product images, pricing, add to cart, badges
reference/components/product-slider.md - Carousel implementation, mobile swipe, accessibility
reference/layouts/home-page.md - Hero, featured categories, product listings
reference/layouts/product-listing.md - Grid/list views, filters, sorting, pagination
reference/layouts/product-details.md - Image gallery, variant selection, related products
reference/layouts/cart.md - Cart items, quantity updates, promo codes
reference/layouts/checkout.md - Multi-step/single-page, address forms, payment
reference/layouts/order-confirmation.md - Order number, summary, delivery info
reference/layouts/account.md - Dashboard, order history, address book
reference/layouts/static-pages.md - FAQ, about, contact, shipping/returns policies
reference/features/wishlist.md - Add to wishlist, wishlist page, move to cart
reference/features/promotions.md - Promotional banners, discount codes, sale badges
IMPORTANT: For each step below, load the referenced files BEFORE implementing that step.
1. Discovery Phase → Read design.md for user preferences
2. Foundation Setup → Read connecting-to-backend.md (or medusa.md for Medusa), mobile-responsiveness.md, seo.md
3. Core Components → Implement navbar.md, footer.md
4. Home Page → Read home-page.md
5. Product Browsing → Read product-listing.md, product-card.md, search.md
6. Product Details → Read product-details.md, product-reviews.md
7. Cart & Checkout → Read cart-popup.md, cart.md, checkout.md, order-confirmation.md
8. User Account → Read account.md
9. Additional Features → Read wishlist.md, promotions.md
10. Optimization → SEO audit (seo.md), mobile testing (mobile-responsiveness.md)
Even if you create an implementation plan, refer back to the skill and load relevant reference files when implementing each step.
Browse → View → Cart → Checkout
Browse: home-page.md → product-listing.md
View: product-details.md + product-reviews.md
Cart: cart-popup.md → cart.md
Checkout: checkout.md → order-confirmation.md
For product grids and filtering → product-listing.md and product-card.md
For product cards → product-card.md
For navigation → navbar.md and megamenu.md
For search functionality → search.md
For checkout flow → checkout.md
For promotions and sales → promotions.md
Before implementing, consider:
design.md to discover design style preferencesMedusa is a modern, flexible ecommerce backend. Consider Medusa when:
For detailed Medusa integration guidance, see reference/medusa.md. For general backend patterns, see reference/connecting-to-backend.md.
All guidance is framework-agnostic. Examples use React/TypeScript where code demonstrations are helpful, but patterns apply to:
Mandatory for launch (core shopping flow):
Nice-to-have (add if time permits):
User-dependent (ask before implementing):
Before implementing, watch out for these common ecommerce-specific pitfalls:
1. Cart and Navigation Mistakes
aria-live="polite" on cart count - Screen readers won't announce cart updates without itposition: relative (megamenu won't position correctly)absolute left-0 on megamenu)right-0 or w-full, not just w-auto)2. Product Browsing Mistakes
/products/[handle] instead of /products/shirt.tsx)3. Product Details Mistakes
4. Design and Consistency Mistakes
reference/design.md before creating ANY UI component - Leads to inconsistent colors, fonts, and styles5. Checkout and Conversion Mistakes
6. Mobile Experience Mistakes
7. Performance and SEO Mistakes
loading="lazy" to images below the fold8. Backend Integration Mistakes
@medusajs/types packageregion_id query parameter (causes missing or incorrect pricing)ssr.noExternal: ['@medusajs/js-sdk'] to vite.config.ts)