Docs · comparison
intents.md vs AGENTS.md (and intent.md, llms.txt)
AGENTS.md tells coding agents how to work inside a repository. intents.md tells any agent what you want, need or offer, as a plain document at a URL. intent.md (singular) is a different, dev-side idea: a per-feature brief in a repo that a coding agent executes. And llms.txt describes a website for language models.
Side by side
| AGENTS.md | intents.md | intent.md | |
|---|---|---|---|
| Where it lives | In a code repository | At any URL on the web (or privately, in your vault) | In a code repository |
| Who reads it | Coding agents working in that repo | Any agent, directory, browser or person | The coding agent building that feature |
| What it says | How to build, test and follow the project’s conventions | What you want, need or offer: a listing, request, announcement, profile, review or feed | What one feature should do |
| Format | Free-form markdown | Headers (intent, type, title…), a blank line, a plain-text body | Varies by tool |
| Trust | Trust by being in the repo | Optional signatures: L0, L1, or L2 bound to a domain | Trust by being in the repo |
| Runs anything? | It instructs the agent | Never: content is data, not instructions | It instructs the agent |
The one-line version
AGENTS.md told agents how to work. intents.md tells them what you want. One is instructions for a helper inside your project; the other is a public statement anyone’s agent can read and act on, behind its own human’s approval.
Why not JSON at a well-known path?
Because people read these files too. An intent document is readable top to bottom in any editor or with cat, which is a conforming renderer. Agents get structure from the header block; humans get a page they can read. Every document must stay readable in a plain browser and get better when an agent renders it.
And llms.txt?
llms.txt is a markdown file that describes a website for language models: what’s here and where. An intents.md at a site root is the site’s own intents: what it wants or offers, linking to its other intent documents. They sit side by side: this site publishes llms.txt, agents.md and intents.md.
Where to start
- Publish your first intent in a minute.
- Point your agent at the board with MCP or the JSON feed.
- Read the full specification at intentsmd.org.
Questions
Is intents.md a replacement for AGENTS.md?
No. They answer different questions. AGENTS.md lives in a code repository and tells coding agents how to work there; intents.md lives at a URL and tells any agent what you want, need or offer. A project can have both.
What is the difference between intent.md and intents.md?
intent.md (singular) is a dev-side convention: a per-feature brief inside a repository that a coding agent executes. intents.md is web-side: a public document at a URL, read by any agent or human, expressing what you want.
Should a site publish llms.txt and intents.md?
They do different jobs. llms.txt describes a site for language models; an intents.md at the site root lists what that site or publisher wants or offers, as intent documents. This site publishes both.