Make prisma.io docs agent-ready: llms.txt split, agent directives, skill.md, MCP discovery

.claude/skills/README.md

@@ -16,6 +16,7 @@ A skill is a folder with a `SKILL.md` (the instructions) and sometimes `referenc
 | [`content-write-blog`](content-write-blog/SKILL.md) | Scaffold a new Prisma blog post (frontmatter + section stubs) | "Draft a blog post about connection pooling" |
 | [`content-create-hero-image`](content-create-hero-image/SKILL.md) | Generate a post's hero (SVG) and social/OG image (PNG) in the Eclipse house style | "Create a cover image for my Compute post" |
 | [`docs-writer`](docs-writer/README.md) | Write or rewrite developer docs (how-to, concept, reference) | "Write a how-to for deploying to Prisma Compute" |
+| [`docs-agent-ready`](docs-agent-ready/SKILL.md) | Hold the docs' agent-readiness invariants (llms.txt budgets, coverage, skill/MCP endpoints) when editing them | "Add a new docs section to llms.txt" |
 
 ---
 

.claude/skills/docs-agent-ready/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: docs-agent-ready
+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.
+metadata:
+  author: Prisma
+  version: "2026.7.21"
+---
+
+# Docs agent-readiness
+
+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`.
+
+## Invariants
+
+- **Root `llms.txt` < 50k bytes** (warn at 35k). It links to per-area section indexes, not every page.
+- **Each section index < 50k bytes** (warn at 40k). Over budget means split the section.
+- **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.
+- **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.
+- **HTML/Markdown parity** via `data-markdown-ignore` on human-only chrome so the Markdown mirrors the page.
+- **`llms-full.txt` excludes** legacy `/orm/v6` and the Accelerate/Optimize products (`getLLMsFullPages`).
+- **Skill + MCP endpoints live at BOTH roots**: `www.prisma.io` (apps/site) and `/docs` (apps/docs).
+
+## File map
+
+| Endpoint | Generated by |
+|---|---|
+| `/docs/llms.txt` | `apps/docs/src/app/llms.txt/route.ts` → `buildLLMsIndexContent` (llms.ts) |
+| `/docs/llms/<slug>.txt` | `apps/docs/src/app/llms/[...slug]/route.ts` → `buildLLMsSectionContent` (llms.ts) |
+| `/docs/llms-full.txt` | `apps/docs/src/app/llms-full.txt/route.ts` → `getLLMsFullPages` (llms.ts) + `getLLMText` |
+| `/docs/<page>.md` | `apps/docs/src/lib/get-llm-text.ts` (`getLLMText`) |
+| `/docs/skill.md` | `apps/docs/src/app/skill.md/route.ts` → `apps/docs/src/lib/agent-skill.ts` |
+| `/docs/.well-known/mcp[.json]` | `apps/docs/src/lib/mcp-discovery.ts` |
+| `/skill.md`, `/.well-known/agent-skills/*` | `apps/site/src/lib/agent-skills.ts` (`buildSkillMarkdown`) |
+| `/.well-known/mcp*` (site) | `apps/site/src/lib/agent-skills.ts` (`buildMcpDiscovery`, server cards) |
+
+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.
+
+## Playbooks
+
+**(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.
+
+**(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.
+
+**(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.
+
+**(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).
+
+**(e) Verification.**
+
+```bash
+pnpm --filter docs lint:agent-ready       # all invariants + size table
+pnpm --filter docs types:check            # types
+curl -s https://www.prisma.io/docs/llms.txt | head
+curl -s https://www.prisma.io/docs/skill.md | head
+curl -s https://www.prisma.io/.well-known/mcp
+```
+
+The guard prints a size table with per-file headroom so reviewers see how close each file is to its budget.

.github/workflows/links.yml

@@ -29,3 +29,6 @@ jobs:
 
       - name: Validate documentation links
         run: pnpm run lint:links
+
+      - name: Validate agent-readiness
+        run: pnpm --filter docs lint:agent-ready

apps/docs/package.json

@@ -14,6 +14,7 @@
     "types:check": "fumadocs-mdx && next typegen && tsc --noEmit",
     "postinstall": "fumadocs-mdx",
     "lint:links": "tsx ./scripts/lint-links.ts",
+    "lint:agent-ready": "tsx ./scripts/lint-agent-ready.ts",
     "lint:external-links": "tsx ./scripts/lint-external-links.ts",
     "lint:images": "tsx ./scripts/lint-images.ts",
     "lint:code": "tsx ./scripts/lint-code-blocks.ts",