---
name: ai-legibility-audit
description: "Audit whether a site is legible to AI answer engines and coding agents, checking only what is mechanically verifiable, not ranking promises. Use before launch, or when adding AI-facing surfaces, to confirm content is server-rendered so a non-JS crawler sees it, there is one h1 and clean heading hierarchy, JSON-LD is present and valid, a sitemap and freshness dates are consistent, a clean per-page markdown endpoint mirrors the HTML, llms.txt is well-formed, and robots.txt names real AI user-agents. It asserts presence and correctness, never that any of it improves how often you get cited."
---

# AI Legibility Audit

Is your site legible to AI, the part you can actually verify? It checks server-rendered content, valid JSON-LD, a clean markdown mirror, a well-formed llms.txt, and AI-crawler robots rules. It grades your site's own bytes, never promises a ranking, because that part is a black box.

## Phases

Work through these in order.

### 1. Fetch

Curl each key route with JavaScript off (the raw HTML a non-JS crawler sees) and confirm the real content, the JSON-LD, the single h1, and the article structure are all present in the initial bytes, not injected after hydration.

Read: [seo](https://selwynuy.dev/d/seo.md)

### 2. Structure

Confirm exactly one h1 and a non-skipping heading hierarchy, semantic article/nav landmarks, descriptive link text and alt attributes, valid JSON-LD whose fields match the visible content, and dateModified consistent with the sitemap lastmod and the visible date.

Read: [seo](https://selwynuy.dev/d/seo.md)

### 3. AI surfaces

Confirm the machine-readable surfaces are present and well-formed: a clean per-page markdown endpoint that mirrors the HTML, an llms.txt in the H1 to blockquote to H2 shape, an AGENTS.md at the repo root, and a robots.txt that names real AI user-agents (GPTBot, ClaudeBot, PerplexityBot, Google-Extended) with the intended allow or disallow.

Read: [how-to-use](https://selwynuy.dev/d/how-to-use.md)

### 4. Report honestly

Report each surface as present, valid, or missing with the byte-level evidence and the standard it was checked against. State plainly that these verify legibility, not ranking or citation, which depend on opaque engines outside the site. Do not turn any unproven GEO tactic into an action item.

Read: [writing-without-ai-slop](https://selwynuy.dev/d/writing-without-ai-slop.md)

## Bundled files

- `scripts/scan-ai-legibility.mjs` (script): Fetches routes and checks the mechanical AI-legibility surfaces (server-rendered content, one h1, JSON-LD, markdown endpoint, llms.txt shape, AI-crawler robots rules), reporting presence and validity only.
- `references/ai-legibility-checklist.md` (reference): Every checkable surface with its verification and the published standard behind it, plus a dated, hedged note on what GEO research suggests and why this skill does not automate it.

---

Part of AI Legibility Audit from Selwyn Uy's Next.js Handbook. Full page: https://selwynuy.dev/skills/ai-legibility-audit