skill.md: An open standard for agent skills

All Mintlify documentation sites now contain a /.well-known/skills/default/skill.md file at their base URL. In accordance with the Cloudflare RFC, agentskills proposal, and Vercel skills CLI. Skill files can be installed into 20+ major coding agents including Claude Code, OpenCode, and Cursor via Vercel's skills CLI.

If you are a Mintlify user, you can replace the autogenerated skill.md file with your own by placing a skill.md file in the root of the git repository behind your project. You may want to do this if you have specific tastes which were not captured by our agent.

Deprecating install.md

Last Friday we announced install.md and it didn't see much adoption. We think skills are a better fit for the use case. They contain both installation and usage knowledge which agents can use more consistently.

Most importantly, there's more momentum behind skills.

Why do skills matter?

Agents have access to all your documentation, yet they often write horrible code.

This isn't because models are unintelligent—with perfect context they excel in most tasks. It's because documentation is largely written for humans, and humans can't look at a block of text containing every feature and best practice and instantly apply them.

Because of this, features and best practices are spread around our documentation for the human to consume as they browse. Often they don't go into much detail because it needs to be digestible to users with varied levels of technical understanding.

Large language models have a different limitation. While they can understand content of arbitrary technical complexity, they can't hold massive amounts of tokens (like your entire site) in context and still perform at their full capacity. AI is also constantly out of date due to being trained on data from the past, and needs up to date context related to the task.

This begs the questions: what information should you always include in the context of an agent so that they can perform to their full capacity? And how do you keep it up to date?

This is where we see skill.md providing the most value. With the right up to date context, the quality of code produced by agents is massively improved. Mintlify regenerates the skill.md file every time you update your docs so it always contains the latest information.

What belongs in skill.md

Skill.md is the information you want agents to always have when working with your product. This can include personal taste, capabilities, limitations, and best practices. Documentation usually scatters this across dozens of pages, or skips it entirely because it would overwhelm or be irrelevant to human readers. Skill.md consolidates it for agents.

How we designed ours

The spec is flexible, so here's what worked for us.

Decision tables for tribal knowledge.

Instead of describing every component, we use tables:

Need	Use
Hide optional details	<Accordion>
Sequential instructions	<Steps>
Code in multiple languages	<CodeGroup>

Agents often struggle making intelligent choices. If there are choices you can confidently make for them, you'll reduce their rate of error.

Explicit boundaries.

We separate "what agents can configure" (redirects, SEO settings) from "requires dashboard setup" (custom domains, DNS). This prevents agents from attempting impossible tasks.

Gotchas section.

Ours includes things like "Never use mint.json—it's deprecated, only use docs.json" and "Every MDX file needs a title at minimum." These are mistakes agents make repeatedly without explicit guidance.

Link out for more information.

The skill.md is a cheat sheet, and not a replacement for docs. We point to the full documentation via llms.txt for anything that needs more context.

For another approach, see the Vercel web design guidelines. It's written in a concise style that's not ideal for human browsing, but excellent for agents.

You can see our full skill.md here.

Get started

Skill.md lives at /.well-known/skills/default/skill.md. On Mintlify, we also serve it at /skill.md for convenience.

Humble ask from us, if you're a builder and Mintlify user, go and copy our autogenerated skill file into your repository, and add a note with your personal taste about how best to use your tool. We will use this to improve our generative agent over time.

We look forward to seeing how the standard evolves over time.