An open set of practices that make any website discoverable, parseable, and comprehensible to AI agents. The scorecard operationalizes the spec into pass/fail checks; the tools run those checks against real sites.
Agent readability is the property of a website that lets AI agents — assistants like ChatGPT, Claude, Copilot, and Cursor, as well as autonomous agents built on top of them — find its pages, fetch their content without wasting tokens on layout chrome, and extract the facts, code, and context a user actually asked for. The goal isn't to turn every page into markdown or build a separate "AI version" of your site. It's to expose the signals agents need alongside the page you already serve to humans.
Discovery is shifting. For a growing share of users, the first answer about a product, a help-center question, or a technical topic comes through an AI agent, not a search engine — and often not the linked site at all. When an agent is the reader, three things change. Tokens cost money, so scraping a 5 MB HTML document to surface two paragraphs is wasteful. Layout and navigation chrome dominates raw HTML by byte count, so agents can miss the content signal altogether and hallucinate from training data. And because agents rarely cite their sources by URL, a site that is opaque to them quietly disappears from conversation.
Agent readability is to AI-mediated discovery what SEO was to search: cheap to implement, compounding in return, and increasingly table stakes. It applies to any website that wants to be read by an agent — documentation portals and developer references are a common and high-value target, but product pages, marketing sites, help centers, and long-form content all benefit from the same practices.
Every check in the scorecard maps to one of these layers. They build on each other: a page agents cannot find never gets parsed, and a page parsed into garbage never gets comprehended.
Can agents find every page you want them to read? Covers
llms.txt, robots.txt (with AI bots allowed),
XML and markdown sitemaps, and AGENTS.md skill files.
Orphaned pages, absent sitemaps, and AI-excluding robots rules all
make a site invisible to agents by default.
Once an agent fetches a page, can it extract the content efficiently?
Covers HTTP basics (no redirect chains, correct content types), HTML
metadata (canonical link, lang, OG, meta description), markdown
mirrors (.md at the same URL with frontmatter), and
content-to-chrome ratio. The cheapest win is usually a mirror — one
.md file per page, served with the right content type.
Once parsed, does the content self-describe? Covers structured data
(JSON-LD with dateModified and BreadcrumbList),
language-tagged code blocks, API schema links, and semantic heading
hierarchy. These are the signals an agent uses to generate
accurate citations, working code examples, and cross-references
that don't hallucinate.
The a14y scorecard is a versioned, frozen manifest of pass/fail checks that maps directly to the three layers above. Each check has a stable id, a documented detection rule, pass/fail examples, and fix guidance — so a failing result is an immediately actionable work item, not a vague "improve your SEO" nudge. Scorecards are frozen once shipped: v0.2.0 always evaluates the same way, so historical scores compare cleanly even as the engine evolves.
Pinning a scorecard version lets teams track trend over time and gate
merges in CI (--fail-under 80) without every engine
improvement resetting the baseline.
The spec is open and evolving. v0.2.0 is the current scorecard — see the check list for exactly what it measures today. New scorecard versions publish additively: older versions stay supported so your existing audits keep reproducing. Contributions, issues, and proposed new checks live on GitHub.
