The Mintlify skill for Claude Code, Cursor, and Codex

We packaged what our team knows about Mintlify into a skill your agent can use.

With it installed, your agent knows how Mintlify works before it touches your repo, from which component fits to how docs.json is structured.

The skill covers the rules, config options, components, CLI, and the hooks we support for customization. The team that builds Mintlify wrote it.

It’s an open source Agent Skill that works with Claude Code, Cursor, Codex, and any other agent that supports skills. If an agent touches your Mintlify project, install it with one command:

Then ask for what you want. The examples in our skill docs start with "Use mintlify to...", followed by the result, your theme, and the pages it touches.

What's in the Mintlify skill?

Think of the skill as a manual. SKILL.md is the table of contents plus the basics every task needs. The eleven reference files are the chapters, and the agent opens only the ones your task calls for.

A typo fix doesn't need the guide to browser events, so it never loads it.

SKILL.mdLoaded for every task: the essentials and an index

When your agent needs toIt also reads

• Start substantial content work, like a new siteproduct-context.md
• Create a page or write more than a sentence or twowriting.md
• Use callouts, cards, steps, tabs, or code groupscomponents.md
• Change the theme, colors, logo, navbar, or redirectsconfiguration.md
• Add tabs, groups, versions, or languagesnavigation.md
• Document an API from OpenAPI or AsyncAPIapi-docs.md
• Restyle the site with CSS, JavaScript, or Reactcustomization/
• Run CLI commands like dev, validate, or broken-linkscli.md
• Publish, branch, undo, or review with suggestionspublishing-and-review.md
• Change domains, auth, members, or workflowsproject-settings.md
• Build or migrate a whole site or sectionsite-building.md

What rules does the skill follow?

Seven rules from SKILL.md and its reference files.

The skill's ruleWhat it means

• Config lives in docs.jsonmint.json is deprecated.
• Every new page goes into navigationPages missing from docs.json navigation don't appear in the sidebar.
• Internal links are root-relativeFor example /getting-started/quickstart, with no ../ paths and no .mdx extensions.
• Code blocks and images are completeEvery code block has a language tag, and every image has descriptive alt text.
• No invented detailsEvery command, flag, default, price, and example must trace to your message, your project, its source code, or a fetched page. Anything else is left out or marked as a visible placeholder.
• Install the mint packageThe CLI's npm package is mint, not the legacy mintlify package.
• Publish only when askedA request to edit is not a request to publish.

How does the skill customize a site?

The skill tells your agent to make every design change the simplest way that works. It tries a built-in setting first and writes custom code only when nothing simpler can do the job.

From simplest to most custom:

1. A docs.json setting. Colors, fonts, logo, or banner. One config value.
2. A component prop. The component already supports it, so the agent passes a prop.
3. A className on one component. Styles one card or callout and nothing else.
4. A React snippet. A small custom component, for when no built-in one fits.
5. Global CSS. Styles that apply to every page.
6. Global JavaScript. Custom code that runs on every page. The last resort.

Settings and props are built-in features. Global CSS and JavaScript reach every page and depend on page structure that can change. The skill even calls the documented CSS selectors "best-effort."

For common requests, the skill skips the list and says exactly where the change goes:

The skill also bans styles tied to generated IDs, test IDs, or utility classes, and :has() selectors that make the browser recheck large parts of the page. Secrets never go anywhere the browser can read.

These prompts come from our skill docs. Copy one and try it:

The skill also tells the agent to check its own work: the first page load, repeated navigation, back and forward, light and dark mode, and the breakpoints it touched. Then report what it verified, and what it didn't.

In our test runs, Claude Code loaded the skill before doing anything else, both times.

How does the skill set up a new site?

Ask for a new docs site and the skill tells the agent to run setup itself from the terminal instead of sending you to a browser quickstart. The steps, from SKILL.md:

1. Check for Node.js v20.17.0 or newer, then install or update the Mintlify CLI.
2. Run mint status. Log in, or create an account with mint signup using details you provide.
3. After you verify your email and finish onboarding, confirm your organization and subdomain.
4. Clone the connected repository. Keep your existing docs, and replace starter content with your Markdown instead of placeholder pages.
5. Preview with mint dev, then run mint validate and mint broken-links and fix any issues it caused.
6. Commit and push to deploy.
7. Confirm your .mintlify.site URL loads before reporting it.

You need a browser for three things: verifying your email, approving OAuth, and connecting GitHub.

What else can you ask your agent to do?

• Write pages. Before a new site or a broad restructure, the skill has the agent write a product brief at .mintlify/product-brief.md: what the product does, who reads the docs, their first tasks, and why the product exists. Later sessions read the brief instead of asking you again.
• Document an API. With an OpenAPI or AsyncAPI spec, the skill references the spec in navigation instead of hand-writing endpoint pages.
• Review a page. Ask for a review and the skill has the agent leave suggestions and comments in the Mintlify editor instead of editing the page.
• Check quality. The skill covers the CLI checks: mint validate, mint broken-links, mint a11y for alt text and color contrast, mint score for agent readiness, and mint test, which generates tests for your code blocks.

How do you connect Mintlify to your AI tools?

The skill gives your agent the know-how to work on a Mintlify project. To actually read and change your docs, it also needs access, which comes from two MCP servers:

• The admin MCP lets it edit your pages, navigation, and settings, and open pull requests, after you sign in with your Mintlify account.
• Your docs' search MCP lets it read your published docs while it codes. Every Mintlify site has one at the /mcp path of its URL, or /authed/mcp if the site requires sign-in.

Here's the setup for each tool:

The first time your tool uses the admin MCP, it asks you to sign in to Mintlify. Mintlify's plugins for Claude Code, Cursor, Codex, and Kiro install the skill and connect the admin MCP and Mintlify's own search server for you.

With the admin MCP connected, the agent doesn't need a local copy of your repo at all. The skill switches it to the MCP tools. It edits on a named branch, previews with the editor link the tools return, and publishes only when you ask. Settings changes go live immediately, so the skill tells the agent to confirm them first.

How is it different from skill.md?

The Mintlify skill, your site's skill.md, and assistant skills are all Markdown that shapes how AI works with docs. Each one serves a different reader.

Read more about skill.md and assistant skills.

Agents already make up nearly 80% of traffic to the docs Mintlify powers. The platform has to work for them as well as it works for people.

Frequently Asked Questions

How do I install the Mintlify skill?

Run the install command at the top of this page, pick your agent and scope, and start a new agent session. You need Node.js and a coding agent that supports skills. In our test, the installer failed on Node.js 20.20 and worked on Node.js 22.

Can I use the skill on an existing Mintlify site?

Yes. It's built for new sites and existing ones. On an existing project, the skill tells the agent to read your docs.json first, search for existing content before creating a page, and read two or three similar pages to match your site's voice, structure, and formatting.

Can the skill migrate existing docs?

Yes. If you're moving from Docusaurus, GitBook, ReadMe, Fern, or Document360, the skill points the agent to the matching migration guide, and tells it to keep your wording and structure, changing only what the format requires. If you'd rather hand it off, our migration team can move your docs.

How do I update the skill?

Rerun the install command with the same options, then start a new agent session. If you got the skill through a Mintlify plugin, update the plugin instead.

Is the Mintlify skill free?

Yes. It's open source under the MIT license.

Where to start

• Install the Mintlify skill and try one of the prompts above
• Connect the admin MCP so your agent can edit and open pull requests without a local checkout