blog: How to Make Your Docs Agent-Ready - #8092
Merged
Merged
Conversation
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.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
WalkthroughAdds a new MDX blog post explaining agent-ready documentation, Prisma’s documented remediation work, audit results, CI enforcement, an audit checklist, and related FAQs. ChangesAgent readiness blog post
Estimated code review effort: 2 (Simple) | ~10 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
|
The latest updates on your projects. Learn more about Argos notifications ↗︎
|
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@apps/blog/content/blog/docs-agent-readiness-score-85-to-99/index.mdx`:
- Line 33: Update the paragraph describing the llms.txt size issue to
distinguish Mintlify’s 50,000-character cutoff from the CI-enforced 50,000-byte
budget in apps/docs/scripts/lint-agent-ready.ts. Use explicit units
consistently, and avoid referring to the same limit interchangeably as
characters and KB.
- Line 39: Update the URL-resolution wording in the document’s affected
explanation sections to distinguish root-relative links such as /docs/page,
which preserve the /docs prefix, from path-relative links such as page or
../page, which can drop it. Apply the correction consistently at both referenced
locations without changing the surrounding context.
- Line 53: Update the `llms-full.txt` row in the readiness score table to avoid
claiming that 4.5 MB guarantees agents can hold the feed without truncation;
describe the smaller size as reducing truncation risk, since the CI budget does
not establish a client limit for this file.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: 6532ede5-9306-42a4-9ba1-479a72342c17
⛔ Files ignored due to path filters (2)
apps/blog/public/docs-agent-readiness-score-85-to-99/imgs/hero.svgis excluded by!**/*.svgapps/blog/public/docs-agent-readiness-score-85-to-99/imgs/meta.pngis excluded by!**/*.png
📒 Files selected for processing (1)
apps/blog/content/blog/docs-agent-readiness-score-85-to-99/index.mdx
Retitle from the score-anchored "85 to 99" framing to "How to Make Your Docs Agent-Ready" (new slug, hero, and meta image to match): the live score already moved to 100 and will keep drifting, so the post now leads with the process and treats the number as a dated snapshot. - Pyramid structure: definition and four properties in the lead, five fixes with a summary table, CI section, then the reader playbook - Voice switched from I to we; date bumped to 2026-07-24 - Five adversarial review rounds (fact, reader-skeptic, positioning lenses in fresh contexts); all quoted output re-verified byte-exact against live endpoints and the live Mintlify report on 2026-07-24 - Honest caveats moved inline to where each claim is made (parity check still failing, MCP probe mechanism, pointer-placement warning) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@apps/blog/content/blog/make-your-docs-agent-ready/index.mdx`:
- Line 118: Update the CI description in the surrounding documentation to say
the llms.txt pointer is required on every indexed page, matching the indexPages
scope enforced by lint-agent-ready.ts, rather than claiming coverage of every
page.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: cc40c3ba-d78c-4d86-bb81-0d6719cb1db5
⛔ Files ignored due to path filters (2)
apps/blog/public/make-your-docs-agent-ready/imgs/hero.svgis excluded by!**/*.svgapps/blog/public/make-your-docs-agent-ready/imgs/meta.pngis excluded by!**/*.png
📒 Files selected for processing (1)
apps/blog/content/blog/make-your-docs-agent-ready/index.mdx
Split long paragraphs into short ones and lists: the four properties in the lead, the three silent failure modes, and the CI invariants are now bullets. Dropped the prose enumeration of the five problems (the table carries it row for row). No factual changes; all reviewed claims, hedges, and caveats intact. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A practical post on making documentation readable by AI coding agents, grounded in the work that took the Prisma docs through Mintlify's Agent Readiness Score.
Framing
The post deliberately does not anchor on the score (it moved 85 → 99 → 100 while this PR was open, and will keep drifting). It leads with what agent-ready means and the five fixes, names the score once as a dated snapshot, and treats the CI guard (
lint-agent-ready.ts) as the durable outcome. The voice is "we", and the closing section is a five-step playbook a reader can run on their own docs.Structure
Definition + four properties in the lead → why agents read docs differently → five fixes (summary table, then one subsection each: index split, per-page pointer, Markdown parity, link resolution via the
/docsbasePath mechanism, skill.md + MCP discovery) → CI section → reader playbook → FAQ (4 accordions, date-qualified).Honest caveats sit inline where each claim is made: the Markdown Content Parity check still flags 1 of 15 sampled pages, the MCP Server Discoverable check probes
/mcpwith an initialize request (discovery documents alone don't count; endpoint work ships separately), and the pointer-placement warning is disclosed where the technique is taught.Verification
llms.txtexcerpt,postgres.mdopening lines, the.well-known/mcpJSON (both paths), and the Mintlify report language (100/100, 30 checks, two failing checks, one warning, thedata-markdown-ignoreremediation text).pnpm checkpasses 6/6 (unrelated reformats excluded from the commit).llms.txt,postgres.md,skill.md,.well-known/mcp), replacing the score-card design.🤖 Generated with Claude Code
Summary by CodeRabbit