How to write an llms.txt file

An llms.txt file is a markdown index that tells AI crawlers how to navigate your documentation, specified at llmstxt.org and supported by ChatGPT Search, Claude, Perplexity and a growing list of other AI search surfaces. Think of it as sitemap.xml for LLMs — but markdown, curated, and readable.

Publishing one takes under ten minutes and moves the llms.txt dimension of your AISO score from 0/10 to 10/10 — a full 10-point lift. This guide walks through the spec, common mistakes, and verification.

Minimum valid format

Per the spec, the only required element is an H1 with the name of the project. Everything else is optional. The minimal valid file is literally one line:

# Acme

That's a valid llms.txt. It won't score well, but it'll parse. A realistic minimum adds a blockquote summary and one H2 section of links:

# Acme

> Acme is an AI customer support platform that resolves tickets autonomously for SaaS teams.

## Docs
- [Quickstart](https://acme.example/docs/quickstart.md): Get up and running in 5 minutes
- [API reference](https://acme.example/docs/api.md): Full REST and GraphQL reference
- [Pricing](https://acme.example/pricing): Plans starting at $49/month

Full example

Here's a richer file using all the spec's conventions — H1, blockquote summary, additional context paragraph, H2 sections, and the special ## Optional section (URLs in there can be skipped if a shorter context is needed):

# Acme

> Acme is an AI customer support platform that resolves tickets autonomously for SaaS teams.

Acme is deployed across 120+ companies and handles 2M+ support tickets per month. The platform integrates with Zendesk, Intercom, and Salesforce, and supports 14 languages. All documentation is versioned and link-stable.

## Docs
- [Quickstart](https://acme.example/docs/quickstart.md): Five-minute setup
- [API reference](https://acme.example/docs/api.md): REST + GraphQL
- [Integrations](https://acme.example/docs/integrations.md): Zendesk, Intercom, Salesforce

## Guides
- [Handoff patterns](https://acme.example/docs/handoff.md): When AI should escalate to a human
- [Prompt library](https://acme.example/docs/prompts.md): Tested prompts for common intents

## Optional
- [Changelog](https://acme.example/changelog.md): Release notes
- [Security](https://acme.example/security.md): SOC 2 + GDPR details

Common mistakes

1. Missing the H1. It's the one required field. Your site name on the first line. Simple.
2. Broken links. AISO samples five URLs from your llms.txt on every scan and fires HEAD requests. Any 4xx/5xx drops your score and flags a high-severity issue.
3. Linking to HTML, not markdown. The convention is markdown endpoints where possible (your HTML docs with .md aliases). Not required, but recommended — it saves crawlers one parse step.
4. Stale timestamps. AISO's freshness dimension looks for a visible Updated date. An old llms.txt is worse than no llms.txt because it signals the site is neglected.
5. Putting it in the wrong place. Must live at /llms.txt at the web root. Not /docs/llms.txt, not /public/llms.txt (unless your framework maps that to root, which is common for Next.js and Vite).

When to ship llms-full.txt

llms-full.txt is the expanded variant: all the linked-from-llms.txt markdown content concatenated inline into one file. The spec names it llms-ctx-full.txt formally, but llms-full.txt is the de-facto community name and AISO checks for both.

Ship it if your documentation is small enough that bundling it as one file is reasonable (<1 MB is a comfortable ceiling). It's worth 2 additional points in the AISO llms.txt dimension. FastHTML, Anthropic docs, and several OSS projects publish both files.

Verify with AISO

After you publish /llms.txt, run a scan at aiso.tools. Navigate to the llms.txt dimension card on your result page — you should see a pass status with 8–10 points awarded. If you ship llms-full.txt as well, the full 10/10 is yours.

For CI integration, add curl https://aiso.tools/api/badge/YOUR-DOMAIN to your README — the SVG badge auto-updates with your live score, so a regression is visible next time anyone opens the repo.