How to Make Your Docs Agent-Ready

Agent-ready documentation is documentation an AI coding agent can discover, fetch, and parse without human help. In practice, that means four things:

• an index small enough to survive a single request, with a route back to it from every page
• a Markdown version of every page that says what the HTML says
• links that resolve from wherever an agent finds them
• machine-readable metadata at the paths agents check

We audited the Prisma docs against the Agent Readiness Score, a public audit from the docs-platform company Mintlify that grades a site on 30 checks (as of this writing), and fixed most of what it found. This post walks through the failures and fixes, then gives you the process to run on your own docs.

The stakes are quiet. A coding agent fetches a docs page mid-task, on behalf of a developer who never sees the request. If the file comes back truncated, or a link leads to a dead end, nothing stops the task. The agent answers from what it got, and the wrong answer shows up in someone's editor with your docs' name on it.

Why agents read docs differently than people

A human reader recovers from a bad docs site. They scroll past the cookie banner, notice the version switcher, and open a second tab when a link breaks.

An agent does none of that. For each page it needs, it makes a request, takes what comes back, and moves on:

• If the index file is cut off partway through, the agent loses everything after the cut, with no reliable way to tell.
• If a link resolves to the wrong path, it hits a dead end or reads the wrong page.
• If the Markdown version of a page is missing a paragraph the HTML has, it answers from the shorter version.

So agent-ready is a different engineering target than readable.

What we fixed in the Prisma docs

When we started, the audit scored the Prisma docs 85 out of 100. Grouped by cause, the missing points came down to five problems, one per row below. (Two terms first: an agent skill is a workflow file an agent can load, and MCP, the Model Context Protocol, is the standard coding agents use to call external tools.)

The five subsections below take these one at a time.

Keep the index small enough to survive one fetch

The llms.txt convention gives agents an entry point: a plain-text file at a fixed URL that lists what the site contains, so an agent can find pages without crawling.

Ours listed every docs page inline, about 116,000 characters. Mintlify's audit currently fails any llms.txt over 50,000 characters, and the limit maps onto a real failure mode: clients cap how much of a feed they read, the caps vary and are rarely documented, and a file this large can be cut off.

The fix was to split it. Each product area now has its own index at /docs/llms/<area>.txt, and the root file is a table of contents pointing at them. Fetching www.prisma.io/docs/llms.txt gives a short list of task-shaped links (start a project, connect a database, check the changelog), then one line per area. Three of the twelve area lines:

## Product Area Indexes

- [`Prisma ORM`](https://www.prisma.io/docs/llms/orm.txt): Current Prisma ORM docs: setup, schema modeling, Prisma Client, migrations, and references (excludes legacy v6 and Prisma Next).
- [`Prisma ORM v6 (legacy)`](https://www.prisma.io/docs/llms/orm-v6.txt): Legacy Prisma ORM v6 documentation, maintained for backwards compatibility only. Prefer the current Prisma ORM section for new work.
…
- [`Prisma Postgres`](https://www.prisma.io/docs/llms/postgres.txt): Prisma Postgres setup, connection strings, local development, operations, and guides.

The root file now serves at about 7,000 characters. CI holds it and every area index under a 50,000-byte budget: bytes are the stricter unit, so staying under it keeps us under the audit's character limit too. The largest index, orm-v6.txt, sits at 37 KB.

Give every page a way back to the index

An agent following a search result or a pasted link lands on a single docs page. Before this work, that page gave it no pointer to the rest of the docs.

Every page now carries one: at the top of the Markdown version, and as a hidden element in the HTML. Hidden, because it is machine housekeeping rather than content; in both formats, because the audit checks both. Fetch www.prisma.io/docs/postgres.md and the first lines are:

# Prisma Postgres (/docs/postgres)

> For the complete Prisma documentation index, see [llms.txt](https://www.prisma.io/docs/llms.txt). A markdown version of any docs page is available by appending `.md` to its URL.

Two sentences, and an agent holding one page can now reach all of them.

One caveat on placement: the checker wants the HTML copy near the top of the page too, and ours renders past the halfway mark. The report flags that as a warning we have not yet cleared.

Make the Markdown match the HTML

Every Prisma docs page is also served as plain Markdown: append .md to its URL. That only helps if the two formats say the same thing, a property audits call Markdown parity.

Ours had drifted in one spot. The build dropped the page description that the HTML rendered, so the .md an agent read was missing the summary a human saw. The fix carries the description through to the Markdown output.

We also tagged HTML-only interface elements, like copy buttons and the "Edit on GitHub" footer, with a data-markdown-ignore attribute. Our Markdown is generated from the MDX source, so those elements were never in the Markdown to begin with, and nothing in our build reads the attribute. It exists for parity checkers: tools that diff the HTML against the Markdown need a way to tell that a missing copy button is interface rather than missing content. It is also the signal Mintlify's parity check asks for when the divergence is intentional, with remediation text that says to "add data-markdown-ignore to human-only HTML elements".

An honest caveat: these changes did not flip the audit's Markdown Content Parity check, which still flags one of its fifteen sampled pages. We have not found which page or what it is missing. The description gap is closed; the check is not.

Make links resolve from anywhere

llms-full.txt is the counterpart to the index: the entire documentation concatenated into one machine-readable file, for an agent that wants everything at once. Ours had two problems, and the link one is the sneakier.

The feed contained about 2,500 links written the way they appear in our source, as root-relative paths like /orm/prisma-client/queries. Those work on the rendered site, because the docs app is served under the /docs base path and the framework prefixes every internal link when it renders HTML. The raw feed gets no such help. Its links appear exactly as written, without the /docs prefix, so a client that follows one lands on prisma.io/orm/..., a page that does not exist.

The fix: rewrite in-body links as full absolute URLs, in the feed and in every per-page .md, so they resolve the same from everywhere.

The feed was also about 7 MB. We dropped legacy Prisma ORM v6 pages and deprecated product pages from it, which took it to 4.5 MB and absorbed the bytes the absolute URLs added. Dropping content is not the same as fixing it, so to be precise: the dropped pages are out of the concatenated feed, not out of the docs. Each one, the 191 Prisma ORM v6 pages included, is still fetchable individually by appending .md to its URL.

Publish the metadata agents look for

Two audit checks scored zero because the documents they look for did not exist at all.

The first is an agent skill: a Markdown file that describes a workflow an agent can load and follow, instead of inferring it from prose. Ours covers Prisma setup and lives at prisma.io/skill.md and prisma.io/docs/skill.md, with a listing at /.well-known/agent-skills that names the skills the site publishes. It carries six frontmatter fields (name, description, license, compatibility, metadata, and allowed-tools), and our CI checks that they stay present. If you want to publish one, ours is a worked example.

The second is discovery for our MCP server. The Prisma MCP server already runs at mcp.prisma.io/mcp; what was missing was a way for an agent on prisma.io to find it. One convention is a small JSON document at a well-known path. curl https://www.prisma.io/.well-known/mcp (the same document serves at /.well-known/mcp.json) now returns:

{
  "version": "1.0.0",
  "transport": "http",
  "url": "https://mcp.prisma.io/mcp",
  "servers": [
    {
      "name": "prisma",
      "url": "https://mcp.prisma.io/mcp",
      "transport": "http",
      "authentication": "oauth"
    }
  ]
}

The same honesty applies here: the audit's MCP Server Discoverable check did not flip. Publishing a discovery document was not enough, and when we dug in, the reason was that the check probes the site's own /mcp path with an MCP initialize request, so a document pointing at a server elsewhere does not count. We are addressing that separately, with an /mcp endpoint on prisma.io that proxies to the same server.

The discovery document cost one route handler and we would publish it again. But treat any fix you have not re-measured as a bet, not a result.

Put the checks in CI, because the score is a snapshot

The most durable change is not any single fix. It is the CI check that keeps them true: lint-agent-ready.ts runs on every pull request into main as pnpm --filter docs lint:agent-ready, asserting among other invariants:

• size budgets on every index file
• every page reachable from the index
• the llms.txt pointer present on every page
• the task-shaped links resolving
• excluded pages staying out of the full feed
• the skill and MCP documents keeping their required fields

An audit tells you where the docs stood on the day it crawled; it does not watch the repository. Without something enforcing these invariants on every pull request, the next few hundred pages of content would undo this work quietly, and nothing would tell you.

As for the score: it moved from 85 to 99 as the fixes landed, and read 100 out of 100 when we checked on July 24, 2026, with no further agent-readiness change from us in between. We would not build a headline on that number. The same report that shows 100 still lists the two failing checks named above, plus the pointer-placement warning, and does not say how the headline number and that detail relate. Rely on the per-check results, which map to things you can fix and verify, and treat the headline as a derived number on someone else's scale.

The lesson that transfers: two of our fixes did not flip their checks on the first pass, and we only knew because we reran the audit. Measure, fix, measure again, then let CI hold the line.

How to audit your own docs

1. Run the audit. Put your docs through the Agent Readiness Score. It crawls the site and reports per-check results, so you start from concrete failures instead of a general sense that things could be better.

2. Group the failures by cause before fixing anything. A report with dozens of checks reads like dozens of problems. Ours reduced to five: an oversized index, a missing per-page pointer, a build gap, a bloated feed with broken links, and missing metadata documents. Fix causes, not checks.

3. Work through the four areas. Our five problems collapse into them: the index and the per-page pointer are both discoverability, and the rest map one each.

   • Discoverability: keep llms.txt small enough to survive a fetch. If yours lists every page inline, move the lists into per-area indexes and leave the root as a table of contents. Then give every page a one-line pointer back to the index, in the Markdown and near the top of the HTML, so an agent that lands mid-site can navigate out; audits check both formats and the placement.
   • Parity: fetch a few of your .md pages and diff them against the rendered HTML. Anything present in one and missing from the other is a divergence an agent inherits. A likely culprit is a frontmatter field the Markdown build never carries through; that was ours. Mark genuinely HTML-only interface elements with data-markdown-ignore so parity tools can tell them apart from missing content.
   • Links: follow the links in your own feeds and confirm they resolve. A link that depends on your framework's base path, or on the URL of the page it sits on, breaks as soon as a client reads it from a feed instead; the fix is to rewrite in-body links as absolute URLs in anything you serve as a feed. While you are there, check the feed's size and prune legacy content an agent does not need by default; ours went from about 7 MB to 4.5 MB.
   • Metadata: publish a skill at /skill.md, and an MCP discovery document at /.well-known/mcp if you run a server. Expect audits to probe for a live MCP endpoint on your origin too, not just the document.

4. Rerun the audit and confirm the checks you targeted actually flipped. Two of ours did not, which we would not have known without rerunning.

5. Put the invariants in CI. Size budgets, reachability, the per-page pointer, link resolution, and your metadata documents' required fields are all cheap to assert, and they catch the regressions that content growth causes.

The finished shape is public if you want to poke at it: llms.txt, skill.md, and the MCP discovery document. Point your agent at them and see what it does.

Frequently asked questions