Docs Agent Ready Agent Skill

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.

2k tokens

context cost

the whole folder, loaded on every use

files

instructions only

copies elsewhere

how many repositories repackaged it

1093

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

npx skills add https://github.com/prisma/web --skill docs-agent-ready

The instruction itself

4 sections, as written by the author

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 keeps a hidden directive as the first child of <body> in the root layout (apps/docs/src/app/layout.tsx), NOT inside the page component. Audits measure the directive's byte position in the body and warn when it sits past 50%, which is where it lands if rendered after the sidebar markup.
HTML/Markdown parity via data-markdown-ignore on human-only chrome so the Markdown mirrors the page. The OpenAPI explorer (APIPage wrapper in src/components/api-page.tsx) carries data-markdown-ignore because the interactive reference has no markdown equivalent — the .md serves the generated API summary instead.
Markdown keeps real headings — fumadocs' processed output emits headings as bare Text [#anchor] lines; getLLMText restores ## markers from the page toc (restoreHeadingMarkers in llm-markdown.ts). Without them, parity checkers strip list-like heading text ("## 1. Set up …") and agents see prose instead of structure.
<details> blocks are converted to a bold summary line + dedented body (formatDetails in llm-markdown.ts); serialized <details> children are 2-space indented, which silently breaks the code fences inside for markdown consumers.
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) |

| /docs/mcp (MCP proxy) | apps/docs/src/app/mcp/route.ts → proxies protocol traffic to mcp.prisma.io/mcp |

| /mcp (site, MCP traffic) | header-matched beforeFiles rewrites in apps/site/next.config.mjs (browser GETs still get the marketing page) |

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. The hidden llms.txt directive lives in apps/docs/src/app/layout.tsx as the first child of <body> — keep it there (before <Banner), never move it into the page component where the sidebar markup would push it past 50% of the HTML. In [[...slug]]/page.tsx, put data-markdown-ignore on any human-only chrome (banners, nav, badges) so it stays out of the parity comparison. New interactive/human-only MDX components should get data-markdown-ignore on their wrapper plus a markdown fallback in normalizeProcessedMarkdown (llm-markdown.ts), following APIPage/formatApiPage.

(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.

pnpm --filter docs lint:agent-ready       # all invariants + size table
pnpm --filter docs test:llm-markdown      # markdown pipeline fidelity snapshots
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.

(f) Reproducing the audit. The audit is the afdocs npm CLI (https://afdocs.dev). To reproduce a report locally:

# version pinned against supply-chain surprises — bump deliberately
npx [email protected] check https://www.prisma.io/docs --sampling deterministic -v
# parity needs its upstream checks in the same run:
npx [email protected] check https://www.prisma.io/docs \
  --checks markdown-url-support,content-negotiation,markdown-content-parity \
  --sampling deterministic --format json -v

Audit gotchas encoded in the invariants above: the HTML directive check needs an <a href*="/llms.txt"> within the first 10% of the (nav/script/style-stripped) <body> on sampled pages and warns when every match sits past 50%; the parity check compares HTML text segments against the .md, strips data-markdown-ignore elements from the HTML side, and only treats a fenced code block as protected when the fence starts at column 0 — which is why <details> bodies must be dedented and headings must keep their # markers. The separate "MCP Server Discoverable" check probes <origin>/mcp with an MCP initialize request (discovery documents alone do not count), which is what the /docs/mcp proxy route and the site /mcp rewrites are for.

Other skills for the same job

different authors, same section of the catalogue

Writing Skills

by ZhanlinCui

×4

Use when creating new skills, editing existing skills, or verifying skills work before deployment

Curated collection of high-quality prompts for various use cases. Includes role-based prompts, task-specific templates, and prompt refinement techniques. Use when user needs prompt templates, role-play prompts, or ready-to-use prompt examples for coding, writing, analysis, or creative tasks.

4k tokens

Edge Strategy Designer

by BaggaT236

×1

Convert abstract edge concepts into strategy draft variants and optional exportable ticket YAMLs for edge-candidate-agent export/validation.

7k tokens scripts

Langgraph Fundamentals

by langchain-ai

vendor ×1

INVOKE THIS SKILL when writing ANY LangGraph code. Covers StateGraph, state schemas, nodes, edges, Command, Send, invoke, streaming, and error handling.

6k tokens

Harness Model Protocol

by ComeOnOliver

×1

Analyze the protocol layer between agent harness and LLM model. Use when (1) understanding message wire formats and API contracts, (2) examining tool call encoding/decoding mechanisms, (3) evaluating streaming protocols and partial response handling, (4) identifying agentic chat primitives (system prompts, scratchpads, interrupts), (5) comparing multi-provider abstraction strategies, or (6) understanding how frameworks translate between native LLM APIs and internal representations.

Translate SKILL.md and README.md files into multiple languages for sharing skills internationally

11k tokens

Agent Setup Maintenance

by langfuse

vendor

| Shared workflow for editing Langfuse's repo-owned agent setup under `.agents/`. Use when changing AGENTS files, shared skills, `.agents/config.json`, generated shim behavior, provider discovery paths, or install-time agent sync.

>- Summarizes Google Cloud Data Lineage graphs to help users debug data quality issues and understand data provenance for BQ/GCS. Use when summarizing upstream and downstream data flows, and presenting complex lineage data as an intuitive Markdown report. Don't use for generic BigQuery queries, editing lineage relationships, or downstream deprecation. Don't use for downstream blast-radius impact analysis (use datalineage-bigquery-asset-impact-analysis skill instead).

2k tokens

How to use it

Copy the folder

Take prisma/docs-agent-ready from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.

Install what it needs

The instructions reference npx. Without those the skill loads but fails at the first command.