llms.txt: writing a guide that coding agents actually follow

An llms.txt is a Markdown file served at the root of a site, at /llms.txt, that gives language models a short, curated entry point: what the product is and where to read more. For coding agents like Claude Code, it works best as a runbook: the exact commands to run, the tools, the rules, what to ask the user first and what to hand back. Write it for an agent that will copy it literally.

What llms.txt is, and what it is not

The llms.txt proposal describes a simple format: an H1 with the name, a blockquote with a one-paragraph summary, then sections with lists of links and short notes. Claude Code’s own documentation index follows it: a title, a summary, then every page with a one-line description.

It is not robots.txt, which tells crawlers what they may fetch, and it is not a sitemap. It is closer to a README written for a model: you choose what matters and say it in plain text, without navigation, banners or scripts.

For a documentation site, an index of links is enough. For a product that an agent operates, such as an API, a CLI or a hosted tool, the agent needs more than links. It needs to act.

Index or runbook: two kinds of llms.txt

	Index	Runbook
Reader	A model answering questions	An agent doing a task
Content	Summary and links to pages	Steps, commands, tools, rules
Success	It found the right page	It finished the task without guessing
Tone	Descriptive	Imperative, with exact values
Typical failure	Stale links	A command the agent rewrote, a rule it skipped

You can combine both: a runbook at the top, then links to the full documentation.

The sections a coding agent needs

In the order the agent will use them:

1. Summary. One blockquote: what the product does and what the agent’s role is.
2. How to read this file. For example: fetch it raw rather than through a tool that summarizes it, and copy commands exactly.
3. Connect. How to authenticate, where the credential goes, how to reuse it in a later session.
4. Commands. One code line per step, ready to paste.
5. Tools or endpoints. Each with its arguments, limits and errors.
6. Rules. Numbered, short, testable: what to do, what never to do.
7. When something is blocked. What to tell the user instead of improvising.
8. What to give the user. The links, the next step, anything they must do themselves.

Write commands an agent can copy exactly

Agents paraphrase. A command described in prose (“create a project with a POST request”) comes back with a different header, a missing flag or a key pasted into the chat. Give the full command, and design it so that copying it is safe:

• One complete command per step. Each command may run in a fresh shell, so do not rely on a variable set three steps earlier.
• Secrets read from a file, never printed. Write the credential to a file outside the repository and read it inside each command.
• Checks built into the command. Stop when a directory is not what you expect, rather than trusting the agent to check.
• Obvious placeholders. my-app with the line “replace my-app everywhere” beats <YOUR_PROJECT> written five different ways.

The guide of agentappbuilder, a prototype canvas for Claude Code, is written this way. Its first step creates a project and saves the response where only the user can read it:

umask 077; mkdir -p /tmp/agentappbuilder && [ -O /tmp/agentappbuilder ] && [ ! -L /tmp/agentappbuilder ] && curl -s -X POST https://app.agentappbuilder.com/api/projects -H 'content-type: application/json' -d '{"name":"My app"}' > /tmp/agentappbuilder/my-app.json

The two checks stop the command if the folder belongs to another user or is a link. Every later command reads the key from that file into a variable and never echoes it. Near the top, the guide also tells agents to fetch it raw with curl -s and to copy its commands and script exactly. The HTTP API reference documents the same calls for people.

Put consent and limits in the rules

The rules section decides what the agent may do alone. Write each rule so that a reviewer can tell whether it was followed:

• “Do NOT modify the app code when the user asks for a prototype” is testable. “Be careful with the code” is not.
• Say what to ask first, and how. When an action sends data off the machine, the agent should ask in one message that lists what goes where, and end with the sentence the user sends back to confirm.
• Say what to do when a step is blocked: tell the user which step, ask them to confirm it in their own words, and never try another route.

The confirmation sentence matters with Claude Code’s auto mode, whose classifier clears a blocked action only when the user’s own message describes it specifically. A guide that has the agent ask “OK?” produces a “yes” that names nothing. Why auto mode blocks an action explains the mechanism. agentappbuilder’s rules are published in full in the rules your agent follows; the same text reaches the agent through the guide, the MCP server’s instructions and every project context result.

Keep it true, and keep it one source

An llms.txt goes stale faster than docs, because nobody reads it in a browser. A few habits help:

• One source of truth. If your docs quote the rules, copy them from the same text, and check in CI that they still match.
• No roadmap. Describe only what works today. An agent that reads “coming soon: GitHub sync” may try to use it.
• Limits with numbers. “HTML of at most 102400 bytes” is actionable; “keep it small” is not.
• Test it with a real agent. Start a fresh session, give only the one-sentence prompt your users will give, and watch which commands it runs. Every improvisation points at a sentence to fix.

Remember that the agent follows this file as instructions, by design. Content you did not write, such as user data returned by your API, should come back labelled as data, never mixed into the guide; prompt injection in agent tools covers why.

A template to start from

# Product name

> One paragraph: what the product does, and what the agent does with it.

Agents: fetch this file raw (curl -s https://example.com/llms.txt) and copy its commands exactly.

## Connect

1. Create a credential: <one complete command that saves the response outside the repository>
2. Call the API: <one complete command that reads the credential from that file>

## Tools

- tool_name {arg, optional_arg?}: what it does, its limits, its main errors.

## Rules

1. When the user asks for X, do Y. Do NOT do Z.
2. Before sending data off the machine, ask in one message and end with the sentence the user sends back.
3. If a step is blocked, tell the user which one. Do not work around it.

## What to give the user

- The link to see the result, and anything they must run themselves.

## Documentation

- [Reference](https://example.com/docs/reference): every endpoint and error.

Conclusion

A useful llms.txt for coding agents is short, literal and testable: exact commands, numbered rules, the consent steps, and what to hand back. Write it for an agent that copies, test it with one, and keep it as the single source your docs repeat. To see one in use, agentappbuilder’s guide at https://app.agentappbuilder.com/llms.txt is what Claude Code reads when you ask it to connect a project.