Markdown
for AI

01 / The shiftYou do not have a model problem. You have a context problem.

A language model arrives with general capability and no idea how your company works. It does not know which products you sell, what your brand may claim, which word you use for the people who pay you, what needs approval, or what changed last Tuesday.

The usual fix is to put the missing information into the model's context. At the simplest level, that means a prompt:

That works. Until the next conversation starts. Then someone pastes it again, slightly differently. Then a second team writes their own version. Within a quarter the sales agent has one definition of the company, the support agent has another, and the marketing agent has a third — and nobody can point at the file where the correct one lives, because there isn't one.

This is not a prompting problem. It is an information architecture problem, and it has the same shape as every information architecture problem before it: knowledge exists, it is scattered, it is unversioned, and the people who need it retrieve the wrong copy.

What is new is the reader. Agents need durable, addressable places to retrieve operating context from. Increasingly, one of those places is a plain text file.

02 / The formatWhy AI keeps converging on .md

JSON, YAML, XML, a database, a proprietary config format — every one of these was available. The industry keeps arriving at a syntax designed in 2004 for bloggers. Five properties explain it.

Structure without scaffolding

This carries hierarchy, and costs almost nothing to express:

Cloudflare put a number on the difference when it launched Markdown for Agents in February 2026: ## About Us costs roughly three tokens, while the HTML equivalent with its class and id attributes burns twelve to fifteen — before any of the wrapper divs, navigation and script tags that pad a real page and carry no semantic information at all. Measured across a whole document, Cloudflare's own announcement post came to 16,180 tokens as HTML and 3,150 as Markdown.

Humans can review it

This matters more than it first appears. Consider an instruction an agent is operating under:

Customer operations understands that sentence. So does legal. So does the engineer reviewing the pull request, who sees exactly this:

No specialist console is required to notice that an autonomous system has just been granted two and a half times more operational latitude. That property — the artefact the machine reads is the artefact the human reviews — is the entire argument, and it is the one thing a vector store, a fine-tune or a config blob cannot give you.

It mixes instruction with explanation

JSON is excellent for a value:

But organisational knowledge is rarely just values. It is also this:

That is prose, and it is the part that prevents the failure. Markdown lets the rule, the reason and the anti-pattern live in one reviewable place without turning the document into a markup project.

It versions

Policies change. Products change. Prices change. What the agent was told when it acted therefore becomes an audit question. Plain text diffs, reviews, approves, reverts and blames using tooling every organisation already owns. For systems with real autonomy, that is not a convenience — it is the evidence trail.

It is not owned by a vendor

The same file can sit in Git, open in Notepad, be indexed in a vector database, injected into a prompt, retrieved by an agent, published to a website, converted to HTML or PDF, and read by a system that does not exist yet. The knowledge is the asset. The .md file is an unusually durable container for it.

New to the syntax itself? The full reference, including how to open and convert .md files on any device, is in MD Files Explained.

03 / The mapThere is no single "AI Markdown file"

The common mistake is treating AGENTS.md, CLAUDE.md, SKILL.md and llms.txt as competing standards. They are not competing. They sit at different levels of the same stack, and the question each one answers is different.

1. 01ConversationWhat does this person want right now? — the prompt
2. 02Persistent instructionsHow should the agent behave here, every session? — AGENTS.md, CLAUDE.md
3. 03ProceduresHow is this particular task performed, when it comes up? — SKILL.md
4. 04KnowledgeWhat must the agent know about the business? — product, policy, brand and domain files
5. 05DiscoveryWhere does an agent find any of this from outside? — llms.txt, Markdown endpoints
6. 06ActionWhat can the agent actually retrieve or do? — APIs, MCP, tools, permissions

Markdown appears repeatedly in levels two to five because those are exactly the levels where information has to be machine-consumable and human-governable at the same time. Level six is not Markdown's job, and treating it as though it were is the most expensive mistake in this whole area — see section 09.

04 / The filesFour formats, four different jobs

Each of these deserves its own explainer, and each will get one. What matters first is the distinction between them: who reads it, and when it loads.

AGENTS.md — the README for agents

A Markdown file at the root of a repository containing what a coding agent needs and a human README should not carry: build commands, test invocations, directory boundaries, conventions, and the things that would get a new contributor into trouble. It came out of collaboration across OpenAI Codex, Amp, Jules, Cursor and Factory, is used by more than 60,000 open-source projects, and is now stewarded by the Agentic AI Foundation under the Linux Foundation.

Three of its design decisions are worth stealing whatever tooling you use:

• No schema. There are no required fields. It is Markdown with whatever headings suit the project — portability comes from the filename, not a specification.
• Nearest file wins. In a monorepo you place one per package and agents read the closest file up the tree. OpenAI's own Codex repository ships 88 of them.
• The human still overrides. Explicit instructions in the conversation beat the file. It is context, not law.

The generalisable principle is scope. An organisation does not need one enormous document explaining everything. It needs the right context at the right level.

CLAUDE.md — what layered context looks like in practice

Claude Code reads CLAUDE.md rather than AGENTS.md. If a repository already has the latter, the documented fix is a one-line import (@AGENTS.md) or a symlink, so both toolchains read one source of truth. The mechanics are the interesting part, because they show what instruction architecture looks like once a system gets serious:

• Four scopes, loaded broadest first: an organisation-managed policy file deployed by IT, a personal user file, the project file in version control, and a gitignored local file for individual preferences.
• Directory walking: files above the working directory load at launch; files in subdirectories load only when the agent works in them.
• Path-scoped rules: a rules file with a paths: glob in its front matter enters context only when a matching file is opened.
• A size discipline: the documentation targets under 200 lines per file, because everything in it is spent from the same budget as the actual work.

Not one enormous prompt. A hierarchy: organisation → team → project → area → task. Some instructions shared, some private, some always present, some relevant only when the agent enters a particular part of the environment. Every enterprise reading this already has an org chart shaped like that.

SKILL.md — progressive disclosure as a file format

Persistent instructions create their own problem: put everything an agent might ever need into permanent context and the context becomes enormous, mostly irrelevant, and expensive. Anthropic's Agent Skills answer it by loading in three stages.

---
name: competitor-analysis
description: Analyse a competitor and
  produce our standard brief. Use when
  someone asks about a named competitor.
---

# Competitor analysis

## Process
1. Identify company and primary product.
2. Review official positioning.
3. Compare against our product.

## Rules
- Prefer primary sources.
- Never infer customer numbers.
- Date every time-sensitive fact.

competitor-analysis: Analyse a competitor and produce our standard brief. Use when someone asks about a named competitor.

This is a document design idea, not a machine learning one. It is how a well-structured Markdown document already behaves for a human who skims the headings and reads only the section they need.

05 / The public surfaceHTML for people. Markdown for agents.

Everything so far happens inside an organisation. The same shift is now visible on the open web, and in February 2026 it stopped being a proposal and became infrastructure.

A website is built for humans and browsers: layout, navigation, cookie controls, interactive components, tracking, advertising. A model retrieving the same page wants the title, the headings, the content, the links and the facts. Everything else is tokens spent on packaging.

llms.txt — the curated map

Proposed by Jeremy Howard of Answer.AI in September 2024, llms.txt is a Markdown file at the root of a site: an H1 with the name, a blockquote summary, then H2 sections of annotated links. A reading list for a model assembling context. The proposal also recommends publishing a clean Markdown version of any useful page at the same URL with .md appended.

Content negotiation — the same URL, two representations

On 12 February 2026 Cloudflare launched Markdown for Agents. On an enabled zone, a client that sends Accept: text/markdown gets Markdown back; a browser sending Accept: text/html gets the normal page. The conversion happens at the edge, with no change to the origin, the CMS or the templates.

Three details in that response repay attention. Vary: accept means caches keep the two representations separate — this is standard HTTP content negotiation, the same mechanism the web has used for decades to serve languages and image formats, not cloaking. x-markdown-tokens hands the agent an estimated token count so it can plan its context window or chunking before reading. And Content-Signal declares how the publisher permits the content to be used. Cloudflare reports that popular coding agents including Claude Code and OpenCode already send these accept headers, and has enabled the feature on its own blog and developer documentation.

This is not unprecedented. We already serve HTML to browsers, JSON to APIs, RSS to feed readers and Schema.org to search engines. Markdown is becoming another representation of the same underlying organisation — optimised not for rendering pixels but for supplying readable semantic context to something that will act on it.

06 / The generalisationEvery company is about to have a context architecture

The mature examples are all from software development because coding agents got there first. The architectural problem is not specific to code.

A retailer running agents across service, ecommerce, merchandising and marketing needs something like this — and note that none of the filenames are a standard. The architecture is the point.

/company
    company.md
    terminology.md

/brand
    positioning.md
    voice.md
    claims.md

/commerce
    pricing.md
    promotions.md
    returns.md
    shipping.md

/customer-service
    escalation.md
    refunds.md

/ai
    instructions.md
    skills/

/agency
    agency.md
    services.md
    process.md

/clients/acme
    client.md
    brand.md
    audience.md
    claims.md
    approvals.md

/clients/globex
    client.md
    ...

/skills
    creative-brief/
    campaign-report/

The agency structure exposes a problem the retail one hides, and it is the reason agencies are the sharpest early case: an agency's context has hard walls in it. Agency knowledge, Client A knowledge and Client B knowledge must never blend, and "we told the agent not to" is not an answer when two of your clients compete. Scoping is not tidiness there. It is the account.

For years companies stored knowledge where people would look for it: SharePoint, Drive, Notion, Confluence, decks, PDFs, CRM notes, Slack threads. Agents introduce a different question:

That question has never been asked of most organisations' knowledge before. It deserves to be designed rather than discovered.

07 / The counterweightDo not put your company in a folder of text files

The enthusiasm around .md produces its own failure mode. Markdown is right for relatively stable semantic context. It is wrong for almost everything else, and using it wrongly produces an agent that is confidently out of date.

The useful test is rate of change. If a fact changes faster than a document review cycle, it belongs in a system and the Markdown should say how to fetch it. The end state is not a company reduced to text files. It is an agent that can tell the difference between context, knowledge, live state, tools and authority.

08 / The craftValid Markdown, useless context

A file can be perfectly formed and still be worthless to an agent. The difference is not syntax. It is how much interpretation you have left on the table.

## Customer service

Try to provide really good service
and generally be helpful.
Escalate things when appropriate.

## Refund escalation

Escalate to a human when:
- the refund exceeds €100,
- payment status is disputed,
- the customer threatens legal action,
- fraud is suspected.

Do not promise that escalation
will result in a refund.

When escalating, include:
1. order ID,
2. customer request,
3. amount,
4. reason,
5. actions already taken.

Six rules cover most of the distance:

• Name the heading after the decision, not the department. ## When to escalate a refund retrieves; ## Important stuff does not.
• Separate facts from instructions. "Enterprise plans support SSO" is a fact. "When SSO is required, recommend Enterprise" is an instruction. Mixing them makes both harder to update and lets a stale fact quietly rewrite a rule.
• Put the boundary next to the capability. Never write "you may issue refunds" without the ceiling, the exclusions, and the thing someone will otherwise try — splitting a refund to stay under the limit.
• Use examples where interpretation is genuinely hard. One worked edge case beats another paragraph of abstraction.
• Keep permanent context small. If something matters for one task, do not make every session carry it. Progressive loading is a pattern, not a vendor feature.
• Give every file an owner and a review date. A context file nobody owns becomes stale documentation, and stale context is worse than missing context, because the agent acts on it with total confidence.

The schema matters far less than having an operating model behind it. Four lines of front matter turn a document into something that can be audited.

09 / The line that matters"It's in the prompt" is not a control

As agents gain autonomy, one distinction does more work than any other: the difference between telling a system what it should do and making it impossible for it to do otherwise.

Three things get confused constantly:

Putting a sentence in company.md does not turn it into a security control. Anthropic makes exactly this distinction in its own documentation: persistent Markdown instructions are context that shapes behaviour, not enforced configuration — where a rule must hold regardless of what the model decides, you use permissions and hooks. That distinction has to survive the move from coding agents to business agents, because the consequences get more expensive on the way.

A defensible agent architecture has six layers, and Markdown is honestly only good at two of them:

• Context

  What should the agent know? — Markdown does this well.

• Instructions

  How should it behave? — Markdown does this well.

• Tools

  What can it reach? — APIs, MCP, integrations.

• Permissions

  What is it allowed to reach, as this user, in this context? — identity and authorisation.

• Controls

  What can it never do, regardless of instruction? — policy engines, hooks, sandboxing.

• Audit

  What did it actually do, and what was it told at the time? — logging plus the versioned context above.

The last row is the one that makes the first two worth doing properly. When the instructions an agent followed are a versioned file with an owner and a diff history, "what was the system told when it did that?" has an answer. When they are a prompt someone pasted, it does not.

This is where the subject stops being about a file format. Deciding what an agent knows, what it may do, and how a person can verify either is agentic experience design — it just happens to be stored in a repository.

10 / Start hereYour first five files

You do not need a knowledge graph, a taxonomy workshop or a platform decision to begin. You need five files, one bounded workflow, and the discipline to add context only when something actually breaks.

Pick a starting point below and the generator will write the five files for you. Edit them until they are true, then hand them to one workflow — a support assistant, a first-draft copy agent, an internal research task — and watch what it gets wrong. Every failure tells you which line to add. That is how the architecture becomes useful rather than decorative.

Loading…

One rule to carry into the editing: write the sentences you are tired of repeating to new employees. Those are almost always the sentences an agent is missing too.

11 / The other sideThe honest objections

This is an emerging area with real disagreement in it. A page that only made the case for Markdown would be marketing. Here are the strongest arguments against, and what we think each one is worth.

12 / FAQShort answers

NextWhere this goes

SourcesWhere the specifics come from

• Cloudflare — Introducing Markdown for Agents (12 February 2026), for the token figures, the header behaviour, the coding-agent observation and plan availability.
• Cloudflare developer documentation — Markdown for Agents, for the implementation detail.
• agents.md, for the format, the 60,000-project figure, nested precedence and Linux Foundation stewardship.
• Claude Code — How Claude remembers your project, for CLAUDE.md scopes, imports, path-scoped rules, the 200-line guidance and the instructions-versus-enforcement distinction.
• Anthropic — Agent Skills overview, for SKILL.md structure and the three loading levels.
• llmstxt.org and Answer.AI (3 September 2024), for the llms.txt proposal and its structure.
• MDN — HTTP content negotiation, for the mechanism behind Accept-header representation switching.
• RFC 7763, for the text/markdown media type being a registered thing rather than a convention.

Verified against these sources on 9 August 2026. This area moves quickly — check the primary source before quoting a figure.