Docs · overview
What is intents.md?
intents.md is an open protocol for publishing what you want, need or offer as a plain markdown file at an ordinary URL. Any agent, directory or browser can read it, and nothing in it can run. A valid document is three header lines (intent, type, title), a blank line, and a body. No SDK, no registry, no account.
AGENTS.md told agents how to work. intents.md tells them what you want. An intent document can be an offer, a request or an announcement. No platform holds the documents and no publisher code ever runs.
A complete intent document
intent: 2 type: listing title: Mountain bike, lightly used ask: 450 CHF contact: mailto:[email protected] Cannondale Synapse, 2023, serviced, Zurich pickup.
That file is complete and valid. intent: 2 is the format version; type says what kind of document it is; title is one line of plain text. Everything after the first blank line is the body. Publishing is the whole standard: write the file, put it at a URL.
Why it exists
Agents are scraping a web built for human eyes. intents.md flips that: publishers ship structured plain text once, and the reader, human or agent, decides what it becomes. Personalisation moves to the reader’s side, with no surveillance, no platform tax and no execution.
The same file works privately too: an intents.md in your own vault, read by your own agents, listing your standing goals. Trust there is by possession, so no signatures are needed.
What it is not
- Not an execution protocol. Documents declare; they never run. Payments, escrow and negotiation happen out of band.
- Not a platform. No registry, no accounts, no client you must install.
- Not JSON in a well-known path. People read these files too:
catis a conforming renderer. - Not
intent.md. See intents.md vs AGENTS.md and intent.md.
The specification
| Document | Status | Defines |
|---|---|---|
| 01 · Core format | Normative | Headers, content types, body rules, rendering tiers, money and secrets, agent safety, render integrity |
| 02 · Trust & integrity | Normative | Trust levels L0–L2, signatures, canonical form, revocation, verifier fetch policy |
| 03 · Trust services & receivers | Non-normative | The anti-abuse ladder, receiver posture, matching and advertising patterns |
The spec lives at intentsmd.org and in the MIT-licensed Goldcote/intents.md repository. It is a draft; additions are by consensus and permanent once added.
What intentsmd.com is
One reference implementation, not the protocol. Post on the campground and your intent becomes a real intent document at /i/<id>, readable by any agent. Agents can search the board through a read-only MCP server and a JSON feed.
Read next
Questions
Is intents.md free to use?
Yes. The protocol is MIT-licensed and the name is free for any conforming implementation. You need a text file and any HTTPS host.
Do I need intentsmd.com to publish an intent?
No. Any markdown file at any URL that parses is a valid intent document. intentsmd.com is one reference implementation: an open board that also publishes what you post as an intent document.
Is intents.md the same as intent.md?
No. intent.md (singular) is a dev-side convention: a per-feature brief inside a code repository that a coding agent executes. intents.md is web-side: a document at a URL, read by any agent or human, saying what you want.
Can an intent document run code?
No. The body is plain text; angle-bracket content is shown literally and only http(s) links and image URLs on their own line are interpreted. The worst a hostile document can do is be a lie.