"llms.txt does not follow recommendations"
A tool told you your llms.txt does not follow recommendations, without saying which one. Here is every rule the format actually defines, which ones are the spec and which are a tool's opinion, and how to tell them apart.
The file parses. A client can read it. It is just not as useful as it could be.
What a tool is actually telling you.
A tool fetched your /llms.txt, compared it against a checklist, and printed a sentence that does not say which item failed. That is the whole message. It is not a standard error string, it does not come from llmstxt.org, and different tools mean different things by it.
This matters more than it sounds, because the llms.txt format has exactly one hard requirement - an H1 - and a long tail of conventions. A warning that lumps the two together tells you nothing about whether you have a broken file or a file that merely differs from the example in the spec.
So the useful question is not "how do I follow the recommendations". It is "which recommendation, and does it come from the spec or from the tool". Everything below is organised around telling those apart.
6 things that produce it.
Ordered by how often they turn out to be the cause, not by how obvious they look.
No H1, or more than one
This is the only element llmstxt.org requires. The file opens with a single "# Project name" heading. A file without one is not a malformed llms.txt so much as not an llms.txt, and every checker flags it. More than one H1 is the same problem from the other direction: a client reading the first heading as the project name will pick up whichever came first, which may not be the one you meant.
# Acme Docs
> Everything a developer needs to integrate Acme.A missing blockquote summary
The "> one-line summary" directly under the H1 is optional in the spec and required by roughly every tool that checks the format, which is how a valid file gets flagged. It is also the single most useful line in the file: it is what a model reads to decide whether the rest is worth fetching. Treat this warning as correct even though it is not, strictly, a spec violation.
# Acme Docs
> REST and webhook documentation for the Acme API, including auth,
> rate limits, and a migration guide from v1.Link lines that are not markdown links
The format is specific: each list item is "- [Title](url)", with an optional ": notes" suffix. Bare URLs, links without a title, and titles without a link all parse as plain text, so a file that looks like a list of links to you contains zero links as far as a parser is concerned. This is the most common real defect behind the warning.
## Docs
- https://acme.com/docs/auth ← not a link
- [Auth](https://acme.com/docs/auth) ← a link
- [Auth](https://acme.com/docs/auth): How to get and refresh a tokenHeadings deeper than H2
The format defines two levels: H1 for the project, H2 for each section. An H3 is not illegal markdown, but nothing in the format says what it means, so a parser either ignores it or treats its contents as belonging to the H2 above. If your file has nested sections, flatten them.
The file is a content dump rather than an index
Some tools warn on size. The reasoning is sound even when the threshold is arbitrary: llms.txt is meant to be small enough that a model reads all of it before choosing what to fetch. Once it is hundreds of kilobytes it has stopped being an index. The expanded content belongs in /llms-full.txt, which exists precisely so llms.txt can stay short.
The file is not what you think it is
Worth ruling out before you edit anything. If your site is a single-page app, a catch-all route may be answering /llms.txt with your HTML shell and a 200 status. Some tools parse that HTML as markdown, find no H1 and no links, and report that it does not follow recommendations - when the real problem is that your llms.txt is not being served at all.
# If this prints <!DOCTYPE html>, your file is not being served.
curl -s https://example.com/llms.txt | head -c 120How to clear it.
Confirm the file is actually served as text
Before fixing the contents, confirm you are looking at the contents. Fetch it and check both the content type and the first bytes of the body. A 200 that returns HTML is the failure that wastes the most time, because every symptom points at the file being wrong rather than absent.
curl -sI https://example.com/llms.txt | grep -i content-type
# want: text/plain or text/markdown - not text/htmlMake the file match the shape the format defines
H1, then the blockquote summary, then optional prose, then H2 sections of links. That order is the format. A file in this shape passes every checker worth running, including ours.
# Acme
> Acme is a payments API for marketplaces. These docs cover auth,
> payouts, and webhooks.
## Docs
- [Quickstart](https://acme.com/docs/quickstart): Auth and first charge in ten minutes
- [Webhooks](https://acme.com/docs/webhooks): Event types, retries, signature verification
## API
- [REST reference](https://acme.com/api): Every endpoint, with request and response shapes
## Optional
- [Changelog](https://acme.com/changelog): Release history back to v1Write notes that describe the destination, not the page
The ": notes" suffix is where the file earns its keep. Its job is to let a model choose between links without fetching them. A note copied from your meta description is written to earn a click from a human and usually says nothing about what the page contains - which is why generated files score well on validators and still fail at the actual task.
Ask the tool which rule it meant
If the file now matches the format and a tool still reports this, the rule is that tool's own. Check whether it is asserting something the spec does not: a required section name, a maximum link count, a mandatory llms-full.txt. Those are opinions. Ours are labelled as ours, which is the only reason you should trust the ones we do assert.
Next to read.
Questions, answered.
Is "llms.txt does not follow recommendations" an official error?
Which parts of the llms.txt format are actually required?
Does a warning like this affect my search rankings?
Should I add llms-full.txt to clear the warning?
How do I check my llms.txt without a tool that hides its rules?
An llms.txt will not fix a site AI cannot read.
Before writing an index for AI clients, check that they can fetch your pages at all. LintPage runs 60 checks against a URL in about 30 seconds - free, no signup.
run a full scan →