Agentic Automation: Skills and MCP That Evolve with Our Product

At Medusa, we're automating our internal operations with AI to increase our efficiency. We're applying this across engineering, documentation, sales, and other operations. This has allowed us to dedicate our resources to more innovative tasks and shipping features faster for our users.

So, we're starting a series of posts around the different agentic automations we have built in the past year. These posts will share how these processes work and our learnings from them. This post is the first in the series.

Problem: Maintain Documentation in AI Toolkit

A few months ago, we shared a post about our self-healing documentation. One of the biggest challenges of working on documentation is making sure it remains up-to-date with fast growing products, especially when they're hosted across workspaces or repositories.

This problem now extends to agentic resources and tools, such as skills and instructions in MCP servers. Our AI toolkit helps agents build sophisticated ecommerce customizations, design storefronts following best user experience practices, and manage deployments on Medusa Cloud.

However, as these tools are spread across projects, maintaining them is even more difficult, but just as important.

AI ToolKit Overview

Before diving into how we implemented agentic automation to ensure our documentation pieces remain in sync across our AI toolkit, let's take a look first at what this toolkit includes:

1. Medusa Development Skills: these are skills that can be installed with skills.sh or as a Claude Code plugin. They contain information on Medusa conventions, how to build customizations in Medusa, how to add widgets to the admin, and more.
2. Docs MCP Server: this MCP server includes a variety of tools that provide agents with documentation-like instructions, such as:
   1. Migration prompts from Shopify, WooCommerce, and Magento to Medusa. They include the steps to take with information related to Medusa's data models.
   2. Provider integration prompts for payment and fulfillment providers. They include the steps to implement a provider with pointers related to different provider types.
   3. Extend product prompt that include instructions for building customizations related to the product data model, such as add a brand or link to a marketplace vendor.
3. Ecommerce Storefront Best Practices Skill: A skill and a Claude Code plugin with knowledge and best UX practices for building an ecommerce storefront, including how to build common UI elements and connect to ecommerce platforms similar to Medusa.
4. Medusa Cloud CLI Skill: A skill and a Claude Code plugin that guides agents in using the Medusa Cloud CLI to manage and debug deployments.

These tools are spread across repositories and are provided in different format. So, the challenge is to keep them up-to-date without having to update every single piece of information manually. Also, as we expand our AI toolkit, it's important to adopt an approach that can be extended across new tools as well.

Existing Docs Automation

Earlier this year, we built an automation system to ensure our docs are kept up-to-date. This automation system tracked changes in Medusa open source and Medusa Cloud, and opened a pull request to update the documentation. It worked across repositories through GitHub Actions that ran Claude Code to translate code changes into documentation changes.

Since sharing the blog post on up-to-date docs with agentic automation, we've expanded the automation flow to also add automation for other tooling, including the Medusa Cloud CLI reference, Medusa Cloud webhooks reference, and automating releases for both Medusa open source and Medusa Cloud. All of those lead to PRs opened to update the documentation.

Extending Docs Automation to AI Toolkit

With the docs automation above, the documentation becomes a reliable source of truth for all Medusa products and remains up-to-date as we ship new features.

So, to ensure that the information in our AI toolkit remains up-to-date as well, we added a new set of automation to each tool that tracks documentation changes. Whenever we update the documentation, it triggers automations across our repositories holding the Medusa skills and docs MCP with what has changed. Then, Claude Code opens a PR against each of those tools with the updates necessary.

For example, when we updated react-router-dom in a recent release which lead to an update in its APIs, this triggered a PR in the medusa-agent-skills repository to update the API used there as well.

Then, our team reviews these PRs and gets them in. The AI toolkit, along with the documentation, remain a reliable source of truth for both agents and humans. We no longer have to spend time on manually finding these inconsistencies and fix them, or expose our users to frustration before we find the outdated information. Our time is spent instead on shipping improvements to both our developer and agentic experiences.

View Automation Flow

Most of our automation flow lives in the docs-automator tool in our open source repository. It shapes inputs coming from different sources into Claude Code prompts that are used to make changes to the documentation.

When documentation PRs are merged, the notify-docs-consumers GitHub action triggers the automation in other repositories, such as the automation in medusa-agent-skills. Those in turn open PRs against their repositories to update them with the documentation changes.

Get Started with Medusa

If you're new to Medusa, check out the documentation, where you'll get a more in-depth understanding of what Medusa is, the commerce features it provides, and how to deploy Medusa to Cloud.