DOCSEARCHbyAlgolia
Submit Docs

Medusa Agent Skills

repository·main·Indexed 41 days ago

https://github.com/medusajs/medusa-agent-skills

A collection of Claude Code plugins and skills designed to assist developers in building Medusa applications. It includes specialized plugins for backend development (medusa-dev), interactive tutorials (learn-medusa), ecommerce storefront best practices (ecommerce-storefront), and Medusa Cloud management (medusa-cloud).

Tokens
176.3K
Snippets
331
Records
616
Agent score
53%

What's inside Medusa Agent Skills

  1. Overview of the Learn Medusa curriculum

    main

    The tutorial is divided into three progressive lessons, each taking approximately 45-60 minutes:

    Lesson 1: Build Custom Features

    • Create a Brand Module (data model, service, migrations).
    • Build a Workflow for creating brands (including rollback logic).
    • Expose an API Route for creating brands (including validation).

    Lesson 2: Extend Medusa

    • Link brands to products using Module Links.
    • Extend core workflows using Workflow Hooks.
    • Query linked data across modules.

    Lesson 3: Customize Admin Dashboard

    • Create a Widget to display brands on the product page.
    • Build a UI Route for managing brands.
    • Use React Query and Medusa UI components.

  3. Use the storefront-best-practices skill

    main

    The storefront-best-practices skill provides comprehensive guidance for building modern, high-converting ecommerce storefronts. It is framework-agnostic (supporting Next.js, SvelteKit, TanStack Start, React, Vue, etc.) and covers UI/UX patterns, component design, SEO, and backend integration.

    When to use this skill:

    • Adding checkout flows (payment, shipping, order placement).
    • Implementing cart functionality (cart pages, popups, add-to-cart).
    • Building product pages (details, listings, grids).
    • Creating navigation (navbar, megamenu, footer).
    • Integrating Medusa backend (SDK setup, products, regions).
    • Building any storefront component (homepage, search, filters, account pages).

    Example prompts to trigger this skill:

    • "Add a checkout page"
    • "Implement shopping cart"
    • "Create product listing page"
    • "Connect to Medusa backend"
    • "Add navigation menu"
    • "Build homepage for store"

  5. Use the mcloud-organizations skill

    main

    The mcloud-organizations skill allows an agent to execute mcloud organizations commands to discover, resolve, and retrieve Cloud organization data. It is useful for finding organization IDs by name, listing all accessible organizations, or retrieving detailed metadata such as membership lists and subscription statuses.

    Allowed Tools:

    • Bash(mcloud organizations*)
    • Bash(mcloud use*)
    • Bash(jq*)

  6. Use mcloud-deployments skill to manage deployments

    main

    The mcloud-deployments skill allows you to execute mcloud deployments commands to inspect deployments, check their status, and retrieve build logs. This is primarily used for monitoring deployment lifecycles and debugging build failures.

    Constraints

    • Always use --json: When parsing output (e.g., with jq), always include the --json flag because plaintext formats are subject to change.
    • Verify Context: Before running commands, ensure your organization and project context are correct by running mcloud whoami --json.
    • ID Formats: Use deployment IDs in the format depl_* or build IDs. Build IDs will automatically resolve to their latest deployment.

  7. Manage Cloud environments with mcloud environments commands

    main

    The mcloud-environments skill allows you to manage the lifecycle of Cloud environments using the mcloud environments CLI. You can list, retrieve, create, delete, redeploy, or trigger new builds for environments.

    Constraints

    • Production Protection: Production environments cannot be deleted. Always verify the type using mcloud environments get --json before attempting a deletion in automated workflows.
    • Non-interactive Mode: Use the --yes flag for destructive operations like delete when running in non-interactive environments.
    • Deployment Logic: Choose between redeploy and trigger-build based on whether the change is in the environment configuration or the source code.
    # Example: List all environments
mcloud environments list --json

  8. Use the mcloud-logs skill to fetch and stream Cloud logs

    main

    The mcloud-logs skill allows you to execute mcloud logs to fetch or stream runtime logs for a Medusa Cloud environment's backend or storefront. You can filter logs by time range, search for specific substrings, filter by metadata, or scope logs to a specific deployment.

    Constraints

    • --follow and --json are incompatible. For programmatic log analysis, use bounded time windows with --from/--to and --json.
    • --follow streams until interrupted with Ctrl+C and should not be used in scripts or pipelines.
    • The default command retrieves the last 500 log lines from the past 15 minutes.

    Allowed Tools

    • Bash(mcloud logs*)
    • Bash(jq*)
    mcloud logs \
  --organization <org-id> \
  --project <project-id-or-handle> \
  --environment <environment-handle> \
  [options]

  9. What is a Workflow and why use one?

    main

    A Workflow is an orchestrator for multiple operations that must complete together. Workflows provide transaction safety (all-or-nothing execution) and automatic rollback via compensation functions. If a step in the workflow fails, the engine automatically calls the compensation functions of all previously successful steps to undo their changes, preventing orphaned data (e.g., creating a database record but failing to upload its associated file to S3).

    Key benefits include:

    • Automatic rollback: Compensation functions undo changes on error.
    • Transaction safety: Ensures atomic operations.
    • Retry logic: Ability to retry failed steps.
    • Composability: Workflows can call other workflows.
    const workflow = createWorkflow("create-brand-with-logo", function (input) {
  const brand = createBrandStep(input)
  const upload = uploadLogoStep({ brandId: brand.id, logo: input.logo })
  return new WorkflowResponse(brand)
})

  10. What is a widget and how does it work in Medusa Admin?

    main

    A widget is a React component injected into an existing admin page at a predefined zone. Unlike a UI route, which creates a completely new standalone page, a widget extends existing pages (e.g., adding information to the product details page) without replacing them.

    Key Characteristics:

    • Non-invasive: Extends pages without modifying core code.
    • Composable: Multiple widgets can occupy the same zone.
    • User-arrangeable: Since Medusa v2.17.2, the position of widgets within a zone is controlled by the admin user via the Layout Composer (Editor view), rather than through code suffixes like .before or .after.
    • Contextual: Widgets receive page data through props (e.g., DetailWidgetProps).
    // Example of defining a widget configuration
export const config = defineWidgetConfig({
  zone: "product.details",
})

  11. Overview of the Medusa Learning Three-Lesson Structure

    main

    The learning-medusa tutorial is structured into three progressive lessons, each lasting approximately 45-60 minutes, for a total commitment of 2-3 hours.

    Lesson 1: Build Custom Features

    Goal: Create a Brand Module, a createBrandWorkflow, and a POST /admin/brands API route. Focus: The layered approach of Module → Workflow → API Route, module isolation, and workflow orchestration/rollback.

    Lesson 2: Extend Medusa

    Goal: Link brands to products, consume the productsCreated hook, and query linked data. Focus: Using Module Links to maintain isolation, Workflow Hooks to extend core flows without forking, and the Query engine for cross-module data retrieval.

    Lesson 3: Customize Admin Dashboard

    Goal: Create a product brand widget and a brands UI route. Focus: Distinguishing between Admin Widgets and UI Routes, React Query patterns, and SDK integration for custom routes.

  12. What is MedusaExec?

    main

    MedusaExec is a capability that allows an AI agent to write and execute arbitrary TypeScript code against a live Medusa server at runtime. Instead of relying on pre-defined endpoints, the agent can generate code to query data, trigger workflows, or update records using full access to the Medusa Dependency Injection (DI) container.

    CRITICAL SECURITY WARNING: MedusaExec executes arbitrary code with full database and service access. You must never expose the agent's POST endpoint or any route that triggers executeCode without admin authentication (e.g., via AuthenticatedMedusaRequest). Unauthenticated access allows attackers to run arbitrary code against your database.