blog: how I raised the docs agent readiness score from 85 to 99

Adds a post walking through the agent-readiness work merged in #8087:
the llms.txt split, per-page directives, Markdown parity, the llms-full.txt
link fixes, skill.md, and MCP discovery, plus a process readers can follow
on their own docs.

Includes the two checks that still fail (Markdown Content Parity and MCP
Server Discoverable) rather than presenting the work as complete.

Author: ankur-arch

apps/blog/content/blog/docs-agent-readiness-score-85-to-99/index.mdx

@@ -0,0 +1,162 @@
+---
+title: "How I Raised the Prisma Docs Agent Readiness Score from 85 to 99"
+slug: "docs-agent-readiness-score-85-to-99"
+date: "2026-07-21"
+authors:
+  - "Ankur Datta"
+metaTitle: "Agent Readiness Score: Prisma Docs from 85 to 99"
+metaDescription: "How I fixed a truncated llms.txt, HTML and Markdown drift, a broken content feed, and missing skill.md and MCP discovery in the Prisma docs, and how to audit yours."
+heroImagePath: "/docs-agent-readiness-score-85-to-99/imgs/hero.svg"
+metaImagePath: "/docs-agent-readiness-score-85-to-99/imgs/meta.png"
+heroImageAlt: "An agent readiness score moving from 85 to 99"
+tags:
+  - "ai"
+  - "education"
+---
+
+A coding agent fetches a Prisma docs page mid-task, on behalf of someone who never sees it. If the page it gets back is truncated, or its links resolve to the wrong path, nothing errors. The agent answers from what it got.
+
+I ran the [Prisma docs](https://www.prisma.io/docs) through [Mintlify's Agent Readiness Score](https://www.mintlify.com/score/prisma), an audit of 30 checks that measures whether a coding agent can discover, fetch, and parse a documentation site. The report came back at **85 out of 100**, a B. Today it shows **99 out of 100**, an A. Here is what was failing, what I changed, and what is still not fixed.
+
+## Why documentation has to work for agents
+
+A human reader can recover 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. It makes one HTTP request, takes what comes back, and moves on. If the index file is cut off partway through, the agent loses everything after the cut and cannot tell. If a link resolves to the wrong path, it follows the link and reads the wrong page. If the Markdown version of a page is missing a paragraph the HTML has, it answers from the shorter version.
+
+None of those failures produce an error. They produce a confident, wrong answer in someone's editor, attributed to your docs.
+
+## What the score found at 85
+
+Failures landed in five areas: content discoverability, Markdown parity, full content discoverability, agent skills, and MCP server discovery.
+
+The largest problem was our own `llms.txt`. The convention is that this file is the entry point: an agent fetches it to learn what the site contains. Ours listed all 631 pages inline, which came to about 116,000 characters. Mintlify fails an `llms.txt` over 50,000 characters, so we were more than double the limit, and the tail of the file was past the point where common agent clients stop reading a text feed.
+
+A page fetched on its own gave the agent no pointer back to the index.
+
+The Markdown build dropped the page description that the HTML rendered, so the `.md` an agent read was missing a summary the human page showed.
+
+The full-content feed, `llms-full.txt`, was 7 MB and contained roughly 2,500 root-relative links. Those lost their `/docs` prefix when a client resolved them against the feed's own URL, so following one landed on a page that did not exist.
+
+Two checks scored zero because the documents did not exist at all: no agent skill definition, and no discovery document for the MCP server that already runs at `mcp.prisma.io/mcp`.
+
+## The changes I made
+
+Each fix targets one way an agent fails. The first column is the failure, the second is what shipped, the third is what it buys an agent.
+
+| Problem | Change | Why it helps agents |
+| --- | --- | --- |
+| `llms.txt` was 116k characters and got truncated | Moved the page list into per-area indexes at `/docs/llms/<area>.txt` and left the root as a table of contents | The whole index survives the fetch, and an agent can pull only the area it needs |
+| A page fetched on its own had no route back to the index | Added an `llms.txt` directive to every page, as a hidden element in the HTML and a blockquote in the Markdown | An agent that lands on one page can find the rest of the docs |
+| The Markdown build dropped the page description | Included the description in the Markdown output, and tagged HTML-only chrome with `data-markdown-ignore` | The `.md` an agent reads carries the same summary the HTML page shows |
+| `llms-full.txt` had about 2,500 links that resolved to the wrong path | Rewrote in-body links to absolute URLs | Links an agent follows from the feed land on the page they name |
+| `llms-full.txt` was 7 MB | Dropped legacy ORM v6 and deprecated product pages, taking the feed to 4.5 MB and absorbing the bytes the absolute links added | A feed an agent can hold without truncating it |
+| No agent skill existed | Published skill documents at `/skill.md` and `/docs/skill.md`, with a listing at `/.well-known/agent-skills` | An agent can load the Prisma setup workflow without inferring it from prose |
+| Our MCP server was not discoverable | Served discovery documents at `/.well-known/mcp` and `/.well-known/mcp.json` | Nothing yet, as far as I can measure. See the honest accounting below |
+
+Dropping v6 removes content rather than fixing it. Those 191 pages are still fetchable individually by appending `.md` to their URL. They are out of the concatenated feed, not out of the docs.
+
+One clarification on `data-markdown-ignore`, because the name oversells it. Nothing in our pipeline reads that attribute. The `.md` output is built from MDX source, not scraped from rendered HTML, so the copy buttons and the "Edit on GitHub" footer were never in the Markdown to begin with. The attribute is the remedy Mintlify's own parity check suggests: it marks those elements in the HTML so the checker can tell they are chrome rather than content the Markdown is missing.
+
+The root index is now a table of contents. Fetching [www.prisma.io/docs/llms.txt](https://www.prisma.io/docs/llms.txt) gives common queries, then one line per area. Three of the twelve lines:
+
+```markdown
+## 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 Next, then …
+- [`Prisma Postgres`](https://www.prisma.io/docs/llms/postgres.txt): Prisma Postgres setup, connection strings, local development, operations, and guides.
+```
+
+Each area index holds its own page list and stays under a 50 KB budget that CI enforces. The largest, `orm-v6.txt`, sits at 37 KB.
+
+The page directive is the other change small enough to copy. It sits at the top of every Markdown page, right after the H1. Fetch [www.prisma.io/docs/postgres.md](https://www.prisma.io/docs/postgres.md) and the first lines are:
+
+```markdown
+# 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.
+```
+
+MCP discovery is a small JSON document at a well-known path, served by a route handler. `curl https://www.prisma.io/.well-known/mcp` returns:
+
+```json
+{
+  "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 server behind that document is the same [Prisma MCP server](/search-prisma-docs-from-your-coding-agent) we already ship. Nothing about it changed.
+
+## Where the score landed, including what did not work
+
+The report now shows **99 out of 100**, a grade A. Of the 30 checks, 24 pass, 2 fail, 3 are skipped as not applicable, and 1 warns. The components are weighted, which is why two failures cost a single point rather than a grade.
+
+The report is published as Markdown at [mintlify.com/score/prisma.md](https://www.mintlify.com/score/prisma.md), so the per-check detail below is quotable rather than something you have to take from me.
+
+Both remaining failures are worth naming, because one of them is a fix in this post that did not take.
+
+**Markdown Content Parity still fails.** This is the check my description fix was aimed at. The report reads: "1 of 15 pages have substantive content differences between markdown and HTML (avg 8% missing)". One sampled page in fifteen, and it is enough to fail the check. I have not yet found which page or what it is missing.
+
+**MCP Server Discoverable still fails**, with "No MCP server was discovered at the expected endpoints." Both discovery documents return the JSON above at both paths. Whatever endpoints the checker probes, these are not them. I published those documents because an audit asked for them, and I have no evidence yet that anything reads that path. That row in the table is a bet, not a result.
+
+There is also a warning I did not clear. The `llms.txt` directive is found in the HTML of all 15 sampled pages, but the checker wants it near the top and ours sits past the halfway mark. The Markdown half passes cleanly. Content discoverability is 6 of 7.
+
+The measurements behind the changes are live. As of July 2026:
+
+```bash
+curl -s https://www.prisma.io/docs/llms.txt | wc -c        # 7031
+curl -s https://www.prisma.io/docs/llms-full.txt | wc -c   # 4517273
+curl -s https://www.prisma.io/docs/skill.md | sed -n 2p    # name: prisma
+```
+
+I also added a CI check, [`lint-agent-ready.ts`](https://github.com/prisma/web/blob/main/apps/docs/scripts/lint-agent-ready.ts), that runs on every pull request into `main` as `pnpm --filter docs lint:agent-ready`. It runs ten assertions: per-file size budgets, every page reachable from the index, the directive present on every page, common-query links resolving, excluded pages staying out of the full feed, and the skill and MCP documents keeping their required fields.
+
+That guard matters more than the score. The audit told me where the docs stood in July; it does not watch the repository. Without something enforcing the invariants on every pull request, the next few hundred pages of content would have undone the work quietly.
+
+## How to do this for your own docs
+
+Start by running your docs through the [Agent Readiness Score](https://www.mintlify.com/score). It crawls the site and reports per-check results, so you get concrete failures instead of a general sense that things could be better.
+
+Read the failed checks before you change anything, and group them by cause rather than by check. Our five failures came down to one file being too large, two documents not existing, link resolution being wrong, and the Markdown build dropping a field. That is fewer changes than a 30-item list suggests.
+
+Then work through the four areas:
+
+- **Discoverability.** Keep `llms.txt` small enough to survive a fetch. If yours lists every page inline, move the page lists into per-area indexes and leave the root as a table of contents pointing at them.
+- **Content 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. The usual culprit is a frontmatter field the Markdown build never carries through.
+- **Metadata.** Publish the documents agents look for: a skill definition at `/skill.md`, and an MCP discovery document at `/.well-known/mcp` if you run a server. A skill needs `name`, `description`, `license`, `compatibility`, `metadata`, and `allowed-tools` in its frontmatter. Ours is readable at [prisma.io/docs/skill.md](https://www.prisma.io/docs/skill.md) if you want a worked example.
+- **Access.** Follow the links in your own feeds and confirm they resolve. Root-relative links that work inside a page break when a client resolves them against a feed URL at a different depth, which is exactly how our 2,500 links went wrong.
+
+Rerun the score when you are done and confirm the checks you targeted actually flipped. Two of mine did not, which I would not have known without rerunning.
+
+Then put the invariants into CI. Size budgets, reachability, and the directive are cheap to assert and catch the regressions that content growth actually causes.
+
+The endpoints are all public if you want to see the finished shape: [llms.txt](https://www.prisma.io/docs/llms.txt), [skill.md](https://www.prisma.io/docs/skill.md), and [the MCP discovery document](https://www.prisma.io/.well-known/mcp). Point your agent at them and see what it does.
+
+## Frequently asked questions
+
+<Accordions type="single">
+  <Accordion title="What is an agent readiness score?">
+An agent readiness score measures how well a documentation site serves AI coding agents rather than human readers. Mintlify's version runs 30 weighted checks across categories including content discoverability, Markdown availability, page size and truncation risk, content structure, URL stability, agent skills, and MCP server discovery, then reports a score out of 100 with a letter grade.
+  </Accordion>
+  <Accordion title="How large can an llms.txt file be before agents truncate it?">
+Mintlify's Agent Readiness Score fails an `llms.txt` over 50,000 characters. Prisma's reached about 116,000 characters in mid-2026, more than double that limit. Prisma now holds the root index to a 50 KB budget enforced in CI, and the file serves at roughly 7,000 characters.
+  </Accordion>
+  <Accordion title="What is the difference between llms.txt and llms-full.txt?">
+`llms.txt` is an index: a short file listing what the documentation contains, with links. `llms-full.txt` is the content itself, the whole documentation concatenated into one machine-readable file. An agent fetches the index to navigate and the full feed when it wants everything at once. As of July 2026 the Prisma index is about 7 KB and the full feed is about 4.5 MB.
+  </Accordion>
+  <Accordion title="Where do agents look for an MCP server?">
+Audits and clients that discover MCP servers by convention request `/.well-known/mcp` or `/.well-known/mcp.json` on the site's root domain. Prisma serves a JSON document at both paths naming `https://mcp.prisma.io/mcp`, its HTTP transport, and OAuth authentication. Publishing those documents did not flip Mintlify's MCP server check, which still scored as failing in July 2026, so treat the path as a convention worth satisfying rather than a solved problem.
+  </Accordion>
+</Accordions>