|
| 1 | +--- |
| 2 | +name: docs-agent-ready |
| 3 | +description: Use when adding a new docs section or product area, editing llms.ts / the llms.txt or llms/[...slug] / llms-full.txt routes / get-llm-text / skill.md / .well-known endpoints, or working on the "agent score", "llms.txt", or anything "agent-ready" in the docs and site apps. Explains the invariants the Mintlify agent-readiness audit measures and how to hold them. |
| 4 | +metadata: |
| 5 | + author: Prisma |
| 6 | + version: "2026.7.21" |
| 7 | +--- |
| 8 | + |
| 9 | +# Docs agent-readiness |
| 10 | + |
| 11 | +Keep Prisma's docs machine-readable so the Mintlify **agent-score** audit does not silently regress as content is added. The score measures whether AI agents can discover and fetch the docs: a working `llms.txt` index, per-page Markdown, a discoverable skill, and MCP discovery. The guard `apps/docs/scripts/lint-agent-ready.ts` (run `pnpm --filter docs lint:agent-ready`) enforces the invariants below on every PR via `.github/workflows/links.yml`. |
| 12 | + |
| 13 | +## Invariants |
| 14 | + |
| 15 | +- **Root `llms.txt` < 50k bytes** (warn at 35k). It links to per-area section indexes, not every page. |
| 16 | +- **Each section index < 50k bytes** (warn at 40k). Over budget means split the section. |
| 17 | +- **Every page is reachable** — each `filterPagesForLLMsIndex` page appears in a section file or the root "Other pages" list. The guard asserts against the generated content, not just membership. |
| 18 | +- **Directives in HTML + Markdown** — every page's Markdown (`getLLMText`) starts with the hidden `llms.txt` directive blockquote; the HTML page keeps a hidden directive as its first child. |
| 19 | +- **HTML/Markdown parity** via `data-markdown-ignore` on human-only chrome so the Markdown mirrors the page. |
| 20 | +- **`llms-full.txt` excludes** legacy `/orm/v6` and the Accelerate/Optimize products (`getLLMsFullPages`). |
| 21 | +- **Skill + MCP endpoints live at BOTH roots**: `www.prisma.io` (apps/site) and `/docs` (apps/docs). |
| 22 | + |
| 23 | +## File map |
| 24 | + |
| 25 | +| Endpoint | Generated by | |
| 26 | +|---|---| |
| 27 | +| `/docs/llms.txt` | `apps/docs/src/app/llms.txt/route.ts` → `buildLLMsIndexContent` (llms.ts) | |
| 28 | +| `/docs/llms/<slug>.txt` | `apps/docs/src/app/llms/[...slug]/route.ts` → `buildLLMsSectionContent` (llms.ts) | |
| 29 | +| `/docs/llms-full.txt` | `apps/docs/src/app/llms-full.txt/route.ts` → `getLLMsFullPages` (llms.ts) + `getLLMText` | |
| 30 | +| `/docs/<page>.md` | `apps/docs/src/lib/get-llm-text.ts` (`getLLMText`) | |
| 31 | +| `/docs/skill.md` | `apps/docs/src/app/skill.md/route.ts` → `apps/docs/src/lib/agent-skill.ts` | |
| 32 | +| `/docs/.well-known/mcp[.json]` | `apps/docs/src/lib/mcp-discovery.ts` | |
| 33 | +| `/skill.md`, `/.well-known/agent-skills/*` | `apps/site/src/lib/agent-skills.ts` (`buildSkillMarkdown`) | |
| 34 | +| `/.well-known/mcp*` (site) | `apps/site/src/lib/agent-skills.ts` (`buildMcpDiscovery`, server cards) | |
| 35 | + |
| 36 | +The route handlers are thin wrappers: shared builders in `llms.ts` are the single source of truth, so the guard measures exactly what the routes serve. |
| 37 | + |
| 38 | +## Playbooks |
| 39 | + |
| 40 | +**(a) Adding a new docs area.** Add an entry to `llmsSections` in `apps/docs/src/lib/llms.ts` with `prefixes` (and `excludePrefixes` if a sub-tree belongs elsewhere). Run `pnpm --filter docs lint:agent-ready`. A **"Catch-all creep"** warning (> 25 pages in root "Other pages") means a new docs area needs its own section here. |
| 41 | + |
| 42 | +**(b) Section over budget.** When a section fails/warns on size, split it into two sections in `llmsSections` (narrower `prefixes`, or carve a sub-tree out with a new slug). Re-run the guard. |
| 43 | + |
| 44 | +**(c) Changing page chrome** in `apps/docs/src/app/(docs)/(default)/[[...slug]]/page.tsx`: keep the hidden `llms.txt` directive as the first child, and put `data-markdown-ignore` on any human-only chrome (banners, nav, badges) so it stays out of the Markdown. |
| 45 | + |
| 46 | +**(d) Changing the CLI workflow or MCP tools** in docs content: update the skill copy in `apps/site/src/lib/agent-skills.ts` AND `apps/docs/src/lib/agent-skill.ts` — they quote real commands and tool names. Keep them in sync with the Prisma Postgres quickstart and `content/docs/ai/tools/mcp-server.mdx`. The `commonQueries` links in `llms.ts` must point to existing pages (the guard fails on stale links). |
| 47 | + |
| 48 | +**(e) Verification.** |
| 49 | + |
| 50 | +```bash |
| 51 | +pnpm --filter docs lint:agent-ready # all invariants + size table |
| 52 | +pnpm --filter docs types:check # types |
| 53 | +curl -s https://www.prisma.io/docs/llms.txt | head |
| 54 | +curl -s https://www.prisma.io/docs/skill.md | head |
| 55 | +curl -s https://www.prisma.io/.well-known/mcp |
| 56 | +``` |
| 57 | + |
| 58 | +The guard prints a size table with per-file headroom so reviewers see how close each file is to its budget. |
0 commit comments