--- title: Common agent-readability mistakes (and how to fix them) description: The agent-readability failures almost every site makes — missing AGENTS.md sections, no sitemap.md, an under-structured llms.txt, no llms-full.txt, stale sitemap.xml — each with a concrete fix. last_updated: 2026-06-12 canonical_url: https://agent-ready.dev/common-agent-readability-mistakes --- # Common agent-readability mistakes (and how to fix them) > The agent-readability failures almost every site makes — each with a concrete fix, ranked by how often they show up in the scan corpus. These are the checks that fail most often across the sites scanned on agent-ready.dev — the live failure rates are on the [State of Agent Readability](https://agent-ready.dev/state-of-agent-readability) report. Each is cheap to fix. To get the exact list for your site, [run a scan](https://agent-ready.dev/agent-readability-score). ## 1. An AGENTS.md that's missing its core sections The most-failed check in the corpus. Many repos ship an [AGENTS.md](https://agent-ready.dev/agents-md-validator) (the skill file that briefs coding agents like Claude Code, Codex and Cursor) but it's a thin paragraph with none of the sections an agent reads. The check wants at least two of **Installation**, **Configuration**, and **Usage**, each with real commands. **Fix:** structure it — spell out how to install, configure and run, with a code block in each: ```markdown # Acme CLI > A command-line tool for managing Acme deployments. ## Installation npm install -g @acme/cli ## Configuration Create acme.config.json in your project root. ## Usage acme deploy --env production ``` Full walkthrough: [how to write an effective AGENTS.md](https://agent-ready.dev/how-to-write-an-effective-agents-md). ## 2. No sitemap.md (or one with no structure) Almost every site has a sitemap.xml; far fewer have a **sitemap.md** — and it's two of the most-failed checks. A sitemap.md is the markdown twin of sitemap.xml: a curated, human- and agent-readable index of your most important pages, which an agent can read and cite directly. Serve it at `/sitemap.md` (or `/docs/sitemap.md`). **Fix:** write a markdown file with H2 sections and descriptive markdown links, not a wall of URLs: ```markdown # Sitemap ## Documentation - [Getting started](/docs/getting-started.md): install and first deploy - [Configuration](/docs/configuration.md): every config option explained ## Guides - [Deploy to production](/guides/production.md) ``` Full guide: [what is sitemap.md (and how to add one)](https://agent-ready.dev/what-is-sitemap-md). On how it differs from the XML version: [llms.txt vs sitemap.xml](https://agent-ready.dev/llms-txt-vs-sitemap-xml). ## 3. An llms.txt that skips the basics An [llms.txt](https://agent-ready.dev/llms-txt-checker) only helps if it follows the shape agents expect. The sub-checks that fail most: **no blockquote summary** after the H1, **no H2 sections** grouping links, and **malformed links** not in `[name](url): description` form. Broken links (a 404 behind a listed URL) are common too. **Fix:** H1, a one-line blockquote, then H2 sections of properly-formatted links: ```markdown # Acme > Acme is a deployment platform for full-stack apps. ## Docs - [Getting started](https://acme.com/docs/start.md): install and first deploy - [API reference](https://acme.com/docs/api.md): complete REST API ``` Step-by-step: [how to add an llms.txt file](https://agent-ready.dev/how-to-add-llms-txt-to-nextjs). ## 4. No llms-full.txt companion A standard llms.txt is a *directory* — it links to pages the agent then fetches one by one. The companion **llms-full.txt** inlines the full content so an LLM gets your whole documentation in a single request. Two-thirds of sites with an llms.txt skip it. **Fix:** generate an expanded file at `/llms-full.txt` that concatenates the actual content of the pages your llms.txt links to (headings, prose, code), built from the same source at deploy time. Full guide: [what is llms-full.txt (and how to generate it)](https://agent-ready.dev/what-is-llms-full-txt). ## 5. A sitemap.xml with no dates A sitemap.xml can be valid and still fail this: more than half of sites omit ``. Without it, an agent can't tell which pages are fresh and which are stale. **Fix:** add an ISO-8601 `` to every `` entry, driven off each page's real last-changed date — not the build timestamp (bumping them all on every deploy is its own anti-pattern): ```xml https://acme.com/docs/getting-started 2026-06-10 ``` ## How to find which of these your site gets wrong Run the full [agent-readability score](https://agent-ready.dev/agent-readability-score) — it checks all of the above plus ~60 more and returns a prioritised fix list specific to your site. See the [State of Agent Readability](https://agent-ready.dev/state-of-agent-readability) report for how your scores compare. ## Frequently asked questions ### What's the most common agent-readability mistake? Shipping an AGENTS.md without its core sections. Across the sites we've scanned, it's the single most-failed check: the file exists, but it has none of the Installation, Configuration, or Usage sections a coding agent reads to learn how to use the project. The fix is structural, not lengthy — two or three labelled sections with real commands and a code example. ### Do I need an AGENTS.md if my site isn't a code project? No. AGENTS.md is for codebases and developer tools — it briefs coding agents (Claude Code, Codex, Cursor) on how to work in your repo. A marketing site or blog doesn't need one, and Agent Ready won't penalise a content site for not having it. Every site, though, benefits from llms.txt and a sitemap.md. ### What's the difference between sitemap.xml and sitemap.md? sitemap.xml is the machine-only XML index search engines have used since 2005 — a flat list of every URL with optional lastmod dates. sitemap.md is a curated, human- and agent-readable markdown index: H2 sections grouping your most important pages with descriptive links. Agents can read and cite a sitemap.md directly; they have to parse XML to use a sitemap.xml. Ship both — they serve different readers. ### How do I find out which of these my own site gets wrong? Run a scan. The Agent Ready scanner checks all of these (and ~60 more) and returns a prioritised fix list with the exact failures for your site. Start at the full agent-readability score, or use the per-spec validators (llms.txt checker, AGENTS.md validator) for a targeted re-check. ### Where do these rankings come from? They're the most-failed checks across the public scans run on agent-ready.dev, deduplicated to one latest scan per domain. The live failure rates — and how they're computed — are on the State of Agent Readability page. The order here reflects that data; the fixes themselves are durable. --- Read the full guide on the web: Scan your site: ## Sitemap See the full [sitemap](https://agent-ready.dev/sitemap.md) for all pages on agent-ready.dev.