# Markdown for AI: Why .md Files Became the Context Layer for Agents > Canonical: https://auxfirst.com/news/markdown-for-ai.html > Markdown representation of this article, for agents and LLM crawlers. Why AI agents use Markdown for instructions, context and skills — AGENTS.md, CLAUDE.md, SKILL.md, llms.txt and Cloudflare Markdown for Agents. ## 01 / The shift — You 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: ``` You are working for Acme. Our primary market is Germany. Never describe Product X as "fully automated." Use "customer" rather than "user" in external copy. ``` 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 format — Why 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: ``` ## Returns Products can be returned within 30 days. ### Exceptions - Personalised products - Opened hygiene products ``` 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. ##### Same page, two representations — Cloudflare's announcement post HTML**16,180 tokens** Markdown**3,150 tokens** An 80% reduction in tokens for the same information. Source: Cloudflare, *Introducing Markdown for Agents*, 12 February 2026. ### Humans can review it This matters more than it first appears. Consider an instruction an agent is operating under: ``` ## Refund authority The support agent may issue refunds up to €100 without manager approval. ``` Customer operations understands that sentence. So does legal. So does the engineer reviewing the pull request, who sees exactly this: ``` - up to €100 + up to €250 ``` 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: ``` { "refund_limit": 100 } ``` But organisational knowledge is rarely just values. It is also this: Refunds above €100 need a manager because some enterprise contracts carry negotiated credit terms. Do not split a refund into several transactions to stay under the limit. 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. The one-line version AI systems need structured context. The people accountable for that context need to be able to read, review and maintain it. Markdown is sitting in the overlap — which is a governance property disguised as a file format. New to the syntax itself? The full reference, including how to open and convert `.md` files on any device, is in [MD Files Explained](https://auxfirst.com/news/md-file-markdown-guide.html). ## 03 / The map — There 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. 01**Conversation**What does this person want right now? — the prompt 2. 02**Persistent instructions**How should the agent behave here, every session? — `AGENTS.md`, `CLAUDE.md` 3. 03**Procedures**How is this particular task performed, when it comes up? — `SKILL.md` 4. 04**Knowledge**What must the agent know about the business? — product, policy, brand and domain files 5. 05**Discovery**Where does an agent find any of this from outside? — `llms.txt`, Markdown endpoints 6. 06**Action**What 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 files — Four 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. | File | Read by | Loaded | Answers | |---|---|---|---| | README.md | People | When a human opens the repo | What is this and how do I start? | | AGENTS.md | Coding agents, cross-vendor | Every session | How does work get done here? | | CLAUDE.md | Claude Code | Every session, by scope | Same, with layering and imports | | SKILL.md | Claude | Only when relevant | How is this specific task performed? | | llms.txt | Models reading your site | At retrieval time | What here is worth reading? | ### 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. company/ ├── AGENTS.md # rules that always apply ├── ecommerce/ │ └── AGENTS.md # only when working here └── billing/ └── AGENTS.md # stricter, narrower ### 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. ##### Level 1 — metadata The YAML front matter, always in context at roughly 100 tokens per skill. The `description` says what it does *and when to use it*. That sentence is the trigger. ##### Level 2 — instructions The Markdown body, loaded only once the skill is triggered. Target: under 5k tokens. ##### Level 3 — resources Bundled references and scripts, read only if the task needs them. Scripts run and return output; their source never enters context at all. **skills/competitor-analysis/SKILL.md**what the agent sees first → ``` --- 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. ``` 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 surface — HTML 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](https://llmstxt.org/) 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. ``` # Acme > Acme builds inventory planning software for European retailers. ## Product - [Platform](https://acme.example/platform.md): what it does, who it is for - [API](https://acme.example/api.md): developer documentation ## Company - [About](https://acme.example/about.md) - [Security](https://acme.example/security.md) ``` ### Content negotiation — the same URL, two representations On 12 February 2026 Cloudflare launched [Markdown for Agents](https://blog.cloudflare.com/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. ``` # ask for the agent representation of any enabled page curl https://blog.cloudflare.com/markdown-for-agents/ \ -H "Accept: text/markdown" # response content-type: text/markdown; charset=utf-8 vary: accept x-markdown-tokens: 725 content-signal: ai-train=yes, search=yes, ai-input=yes ``` 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. What this actually changes Your website now has two audiences with different needs at the same address. One asks *what should I click?* The other asks *what should I read?* Those are different design problems, and until now only one of them had a designer. 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 generalisation — Every 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. Retailer ``` /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/ ``` Advertising agency ``` /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: **What is the smallest authoritative set of information an agent needs in order to act correctly on this business, this client, this product, this task — and who is accountable for keeping it true?** That question has never been asked of most organisations' knowledge before. It deserves to be designed rather than discovered. ## 07 / The counterweight — Do 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. | Information | Belongs in | Because | |---|---|---| | "Our brand sounds calm and specific." | Markdown | Stable, interpretive, needs prose | | "Customer 487 owes €1,238." | CRM / database | Changes constantly, must be exact | | "Refunds above €500 need approval." | Markdown *and* an enforced rule | Stating it is not enforcing it | | "This user may approve refunds." | Authorisation system | Identity is not documentation | | "Here is how we investigate a refund." | Skill / Markdown | A procedure, loaded when relevant | | "Current stock is 418 units." | Inventory API | True for minutes at a time | | "Never promise stock before checking the ERP." | Markdown | A rule about how to use the API | 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 craft — Valid 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. Leaves everything to interpretation ``` ## Customer service Try to provide really good service and generally be helpful. Escalate things when appropriate. ``` Decidable ``` ## 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. ``` --- owner: Customer Operations reviewed: 2026-08-01 review_cycle: quarterly --- ``` 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: ##### Guidance "Prefer our approved terminology." A preference. Violating it is a quality issue. ##### Policy "Customer financial data may not leave the organisation." A rule. Violating it is an incident. ##### Enforcement The agent cannot send customer financial data to an unapproved destination, whatever it decides. A control. 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](https://auxfirst.com/agentic-user-experience.html) — it just happens to be stored in a repository. ## 10 / Start here — Your 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. /ai-context ├── company.md # what the business is, and is not ├── products.md # what you sell, and what you may not claim ├── customers.md # who you serve, who you don't ├── terminology.md # the words everything gets wrong └── instructions.md # rules for agent-generated work 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. Context starter pack · generated locally Copy this file Download .md ###### Organisation type B2B software Agency / studio Retail / ecommerce Professional services ``` Loading… ``` Nothing is sent anywhere — the files are built in your browser. Replace every placeholder before an agent reads them. 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 side — The 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. "There is no evidence any of this improves AI visibility" Correct, and worth saying plainly. No major AI engine has committed to `llms.txt` as a ranking or retrieval signal, and prominent voices in search have publicly questioned whether serving Markdown to bots helps at all. Anyone selling you Markdown endpoints as an AI-SEO tactic is ahead of the evidence. The defensible case is different: content negotiation demonstrably reduces the tokens an agent spends to read you, and a curated index forces you to answer which twenty pages actually represent the business. Both are worth doing on their own merits. Neither is a ranking promise. "Serving different content to bots is cloaking" Cloaking means serving *different content* based on who is asking. Content negotiation serves the *same content in a different representation* based on what the client asked for — the mechanism HTTP has used for decades to deliver languages, encodings and image formats, and it advertises itself with a `Vary` header. The line is substantive, not technical: if your Markdown says something your HTML does not, you have a problem, and it is not a formatting problem. "We will end up maintaining two versions of everything" A legitimate risk, and the reason to prefer generated representations over hand-written duplicates. Edge conversion and build-time generation both derive the Markdown from the same source. If you find a person manually keeping a `.md` twin in sync with a page, the architecture is wrong. "Markdown is too loose for something an agent acts on" Sometimes true. Where a value must be parsed deterministically, put it in structured data and reference it from the Markdown. The prose layer is for the reasoning, the exceptions and the anti-patterns — the parts that a schema cannot express and that a person needs to review. Use both. "Context files will just become the new stale wiki" This is the objection we take most seriously, because it is what usually happens. The difference is ownership and review cadence, not format — which is why the owner and review-date front matter in section 08 is not decoration. A context file without an accountable owner will rot exactly like the intranet did, with the added hazard that something now acts on it automatically. "These formats will be obsolete in two years" Some of the filenames probably will be. The underlying decisions — what context exists, at what scope, owned by whom, loaded when, enforced how — will outlive any of them. Build the architecture so the filenames are replaceable. ## 12 / FAQ — Short answers Why do AI agents use Markdown? It carries document structure — headings, lists, tables, code — in plain text, so a model gets hierarchy at a fraction of the token cost of HTML, and a person can still read, edit and review it. Cloudflare measured an 80% token reduction converting one of its own pages from HTML to Markdown. Is Markdown better than JSON for AI? Not universally. JSON is better where information has a strict schema and must be processed deterministically. Markdown is better for instructions, procedures, explanations and contextual knowledge that humans also have to maintain. Most real systems use both, with the Markdown explaining how to use the structured data. What is AGENTS.md? An open, tool-agnostic Markdown convention for giving coding agents repository-specific context: setup commands, test procedures, conventions and boundaries. It reports use across more than 60,000 open-source projects and is stewarded by the Agentic AI Foundation under the Linux Foundation. What is CLAUDE.md? The persistent-instruction file Claude Code reads. It supports organisation, user, project and local scopes, imports from other files, and rules scoped to particular paths. If your repository already has an `AGENTS.md`, import it from `CLAUDE.md` rather than duplicating it. What is SKILL.md? The instruction file at the root of an Anthropic Agent Skill. Its YAML front matter is always in context so the skill can be discovered; the body loads only when the skill is triggered; bundled resources and scripts load only if the task needs them. What is llms.txt? A proposal for a Markdown file at your site root that gives models a curated index of your important content, optionally linking to clean Markdown versions of pages. It is an emerging convention with meaningful adoption among documentation platforms — not a web standard, and not a confirmed ranking signal. What is Cloudflare's Markdown for Agents? A feature launched on 12 February 2026 that converts HTML to Markdown at the edge when a client requests `text/markdown` via the HTTP Accept header, with no origin changes. Responses carry `Vary: accept`, an `x-markdown-tokens` estimate and a content-signal header. It is available in beta on Pro, Business and Enterprise plans. Should every page have a Markdown version? No. Pages with substantial informational content — documentation, references, product and policy pages — are the strongest candidates. Transactional and interactive pages usually are not. The principle is that an agent should be able to retrieve the useful information without the interface around it. Can Markdown enforce a security policy? No. It can state one. Enforcement belongs to permissions, authentication, sandboxing and policy controls. Confusing the two is the most common and most expensive mistake in this area. Where do I start if we have nothing? Five files, one workflow, and additions driven by observed failures rather than by a taxonomy designed in advance. Section 10 generates the five. ## Next — Where this goes ##### Start with the format [MD Files Explained: The Complete Markdown Guide](https://auxfirst.com/news/md-file-markdown-guide.html) — what a `.md` file is, how to open one on any device, the full syntax reference, flavours and conversion. ##### Then make it operational **MD Files for Business: Building Your AI Context Layer** — the file set, the ownership model and the wizard. Publishing next in this series. ##### Then govern it **Markdown for Enterprise AI: Context, Governance and Control** — scopes, approvals, provenance, conflicting instructions, and auditing what the agent was told. ##### Or start with the practice [Five steps to becoming an agentic organisation](https://auxfirst.com/5steps.html) — where context architecture sits in the wider transition. ## Sources — Where the specifics come from - [Cloudflare — Introducing Markdown for Agents](https://blog.cloudflare.com/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](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/), for the implementation detail. - [agents.md](https://agents.md/), for the format, the 60,000-project figure, nested precedence and Linux Foundation stewardship. - [Claude Code — How Claude remembers your project](https://code.claude.com/docs/en/memory), for CLAUDE.md scopes, imports, path-scoped rules, the 200-line guidance and the instructions-versus-enforcement distinction. - [Anthropic — Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview), for SKILL.md structure and the three loading levels. - [llmstxt.org](https://llmstxt.org/) and [Answer.AI](https://www.answer.ai/posts/2024-09-03-llmstxt.html) (3 September 2024), for the llms.txt proposal and its structure. - [MDN — HTTP content negotiation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Content_negotiation), for the mechanism behind Accept-header representation switching. - [RFC 7763](https://www.rfc-editor.org/rfc/rfc7763.html), 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. --- Written by Emil Krzemiński, founder of auxfirst — https://auxfirst.com/about.html More: https://auxfirst.com/llms.txt © 2026 auxfirst agency · Agentic Experience Design