Scorecard v0.2.0
Initial public scorecard for the Agent Readability Spec. Covers site discoverability (llms.txt, robots.txt, sitemaps, AGENTS.md) and per-page HTML/markdown/code/API checks.
Site checks
Evaluated once per audit against the site's origin. These cover discoverability surfaces — llms.txt, robots.txt, sitemaps, and agent skill files.
Discoverability · 14 checks
- llms-txt.exists llms.txt is published Pass if llms.txt or llms-full.txt is reachable at /, /.well-known/, or /docs/.
- llms-txt.content-type llms.txt served as text/plain Pass if the llms.txt response Content-Type starts with text/plain.
- llms-txt.non-empty llms.txt is not empty Pass if the llms.txt body has any non-whitespace content.
- llms-txt.md-extensions llms.txt links use .md or .mdx Pass if every link in llms.txt points at a .md or .mdx URL (the format agents can ingest cleanly).
- robots-txt.exists robots.txt is published Pass if /robots.txt returns a 2xx response.
- robots-txt.allows-ai-bots robots.txt allows AI bots Pass if robots.txt does not disallow GPTBot, ClaudeBot, CCBot, or Google-Extended from fetching the site root.
- robots-txt.allows-llms-txt robots.txt does not disallow llms.txt Pass if /llms.txt and /.well-known/llms.txt are reachable to all user-agents per robots.txt rules.
- sitemap-xml.exists sitemap.xml is published Pass if /sitemap.xml (or sitemap_index.xml / sitemap-index.xml) returns a 2xx response.
- sitemap-xml.valid sitemap.xml parses as urlset or sitemapindex Pass if the sitemap parses as XML and contains <urlset> or <sitemapindex>.
- sitemap-xml.has-lastmod sitemap entries include <lastmod> Pass if every <url> in sitemap.xml has a <lastmod> child.
- sitemap-md.exists sitemap.md is published Pass if /sitemap.md, /docs/sitemap.md, or /.well-known/sitemap.md returns a 2xx response.
- sitemap-md.has-structure sitemap.md has headings and links Pass if sitemap.md contains at least one heading and one link.
- agents-md.exists AGENTS.md (or equivalent) is published Pass if any of AGENTS.md, agents.md, .well-known/agents.md, docs/AGENTS.md, llms-full.txt, CLAUDE.md, .cursor/rules, or .cursorrules is reachable.
- agents-md.has-min-sections agent skill file documents at least 2 of install/config/usage Pass if the discovered skill file has heading-level sections matching at least 2 of: installation, configuration, usage/examples.
Page checks
Evaluated for every discovered page. These cover HTTP basics, HTML metadata, structured data, content structure, markdown mirrors, code blocks, and APIs.
HTTP · 4 checks
- http.status-200 Page returns HTTP 200 Pass if the final response status (after redirects) is exactly 200.
- http.redirect-chain Redirect chain is at most 1 hop Pass if the page was reached with 0 or 1 redirect hops.
- http.content-type-html Content-Type is text/html; charset=utf-8 Pass if the response Content-Type is text/html and declares utf-8 charset. N/A on URLs with non-HTML extensions (.md, .json, .xml, etc.).
- http.no-noindex-noai x-robots-tag does not block agents Pass if the x-robots-tag response header does not contain noindex, noai, or noimageai.
HTML metadata · 5 checks
- html.canonical-link Has <link rel="canonical"> Pass if the page declares a canonical URL via <link rel="canonical">. N/A on non-HTML responses.
- html.meta-description Has meta description (>= 50 chars) Pass if <meta name="description"> exists and its content is at least 50 characters.
- html.og-title Has og:title Pass if <meta property="og:title"> exists with non-empty content.
- html.og-description Has og:description Pass if <meta property="og:description"> exists with non-empty content.
- html.lang-attribute Root <html> has lang attribute Pass if the <html> element declares a lang attribute.
Structured data · 3 checks
- html.json-ld Has parseable JSON-LD block Pass if the page has at least one <script type="application/ld+json"> block whose content parses as JSON.
- html.json-ld.date-modified JSON-LD declares dateModified Pass if any JSON-LD node on the page contains a non-empty dateModified field.
- html.json-ld.breadcrumb JSON-LD declares a BreadcrumbList Pass if any JSON-LD node on the page has @type "BreadcrumbList".
Content structure · 3 checks
- html.headings Has at least 3 section headings Pass if the page contains 3 or more <h1>/<h2>/<h3> headings.
- html.text-ratio Text-to-HTML ratio is above 15% Pass if visible body text takes up more than 15% of the raw HTML byte length.
- html.glossary-link Links to a glossary or terminology page Pass if the page contains an <a> whose text mentions glossary or terminology.
Markdown mirror · 6 checks
- markdown.mirror-suffix Has .md or .mdx mirror Pass if the corresponding <page>.md or <page>.mdx URL returns 2xx.
- markdown.alternate-link HTML declares <link rel="alternate" type="text/markdown"> Pass if the HTML page advertises a markdown alternate via <link rel="alternate">.
- markdown.frontmatter Markdown mirror has required frontmatter Pass if the markdown mirror has YAML frontmatter declaring title, description, doc_version, and last_updated.
- markdown.canonical-header Markdown mirror sends canonical Link header Pass if the markdown mirror response includes a Link header with rel="canonical".
- markdown.content-negotiation Server returns markdown for Accept: text/markdown Pass if refetching the page URL with Accept: text/markdown returns a text/markdown response.
- markdown.sitemap-section Markdown mirror includes a Sitemap section Pass if the markdown mirror body contains a "## Sitemap" heading.