Markdown for AI

Large language models read and write Markdown by default. They learned it from their training data, chat apps render it, and a growing set of AI instruction files are written in it. Here is why, and how to use it well.

Covers prompt structure, token savings, and the Markdown files AI tools look for: README.md, AGENTS.md, llms.txt, and CLAUDE.md.

Short answer

ChatGPT, Claude, and Gemini answer in Markdown because it fills their training data, chat apps render it, and it marks structure (headings, lists, code) in a character or two instead of HTML tags. For long prompts, use the same tools: a heading per part, bullets for rules, and fences around the text the model should work on. For coding agents and websites, use the Markdown files they look for: AGENTS.md for repo instructions, CLAUDE.md for Claude Code, and llms.txt for agents reading your site.

Jump to Section

Why LLMs Prefer It Tokens: HTML vs Markdown Structuring Prompts The AI Markdown Files AGENTS.md llms.txt Markdown in AI Tools Best Practices Quick Reference FAQ

Why LLMs Prefer Markdown

Ask ChatGPT, Claude, or Gemini a question and the answer comes back with headings, bold text, bullet lists, and fenced code. That is partly a product decision: the chat apps render Markdown, and OpenAI's Model Spec says assistant output should be Markdown unless the user asks otherwise. It also suits models: the syntax is familiar from training, cheap in tokens, and carries structure that plain text throws away.

They know it, and chat apps render it

READMEs, docs sites, and developer forums are written in Markdown, and that kind of text is a staple of training data. Chat apps render it, and OpenAI's Model Spec tells its models to answer in Markdown by default.

It is token-efficient

A heading is one # character; bold is two asterisks. HTML needs opening and closing tags, and real pages add navigation, scripts, and attributes on top. Fewer tokens leaves more context for content.

It encodes structure

Headings, lists, and code fences map directly to the document hierarchy a model reasons over. Plain text loses that structure; Markdown keeps it human-readable and machine-parseable at once.

Tokens: HTML vs Markdown

Every character you send to a model costs tokens, and your context window is finite. HTML wraps each element in opening and closing tags; Markdown encodes the same structure with one or two characters. The two snippets below describe the exact same content, but the Markdown version is shorter, which leaves more of the budget for the content that matters.

HTML — heaviermore tokens

<h2>Installation</h2>
<p>Run the following command:</p>
<pre><code>npm install acme</code></pre>
<ul>
  <li>Requires Node 18+</li>
  <li>Works on macOS and Linux</li>
</ul>

Markdown — lighterfewer tokens

## Installation

Run the following command:

```
npm install acme
```

- Requires Node 18+
- Works on macOS and Linux

Real numbers: Cloudflare measured one of its own blog posts at 16,180 tokens as HTML and 3,150 as Markdown, about 80% fewer (source). Most of that comes from dropping navigation, scripts, and attributes, not just shorter tags; on clean, minimal HTML like the snippet above the gap is far smaller. That is why scrapers, RAG pipelines, and AI browsers convert pages to Markdown before sending them to a model.

Structuring Prompts with Markdown

For anything beyond a one-line question, structure helps. Use a top-level heading for the goal, sub-headings for each part of the task, bulleted lists for rules, and fenced blocks or blockquotes for the content the model should act on. This separates instructions from content and gives the model an outline to follow.

A well-structured prompt

# Role

You are a senior technical editor.

## Task

Rewrite the text below to be clearer and more concise.

## Rules

- Keep the original meaning
- Use active voice
- Target a 9th-grade reading level

## Text to edit

> The utilization of verbose terminology frequently
> impedes comprehension on the part of the reader.

How the model sees the structure

Role

You are a senior technical editor.

Task

Rewrite the text below to be clearer and more concise.

Rules

Keep the original meaning
Use active voice
Target a 9th-grade reading level

Text to edit

The utilization of verbose terminology frequently
impedes comprehension on the part of the reader.

Why it works: the headings tell the model what the goal is versus what the rules are; the blockquote clearly marks the text to edit, so the model is less likely to mistake it for another instruction. New to the syntax? Start with the Markdown cheat sheet.

Does the format matter? Sometimes a lot. One study found GPT-3.5's scores moved by up to 40% just by switching the same prompt between plain text, Markdown, JSON, and YAML, while GPT-4 was more robust and no format won everywhere (He et al., 2024). The vendors' advice differs too: OpenAI's GPT-4.1 guide says to start with Markdown headings, and Anthropic recommends XML tags such as <instructions> for Claude. Both work; clear separation of instructions from content is what matters.

The AI Markdown Files

A new family of Markdown files has appeared specifically to talk to AI. They share one idea: a predictable filename and plain Markdown content that a model can read without guessing. Here is how the main ones fit together.

File	Where it lives	Read by	Purpose
README.md	Repository root	Humans first, agents as fallback	Project overview, quick start, and contribution basics.
AGENTS.md	Repo root + nested per package	Coding agents (Codex, Cursor, Copilot, Jules, Claude Code…)	Build, test, and style instructions an agent needs to work on the code.
CLAUDE.md	Repo root and ~/.claude/	Claude Code	Claude-specific project guidance. Claude Code reads AGENTS.md only when no CLAUDE.md exists, unless CLAUDE.md imports it with @AGENTS.md.
llms.txt	Site root (/llms.txt)	AI agents on demand, mostly coding agents (Google Search ignores it)	A curated, low-noise Markdown map of a site's most important pages.
.cursorrules / .windsurfrules	Repo root	Single-tool (legacy)	Older single-file rules. Both editors now use a rules folder (.cursor/rules, .windsurf/rules) and also read AGENTS.md.

AGENTS.md — a README for coding agents

AGENTS.md is a plain Markdown file at the root of a repository that tells AI coding agents how to work on your project: the build and test commands, code-style conventions, and any gotchas. There are no required fields, so use whatever headings make sense. Over 60,000 open-source projects ship one (per agents.md), and it is read by Codex, Cursor, Copilot, Jules, Claude Code, and most other agents.

Example AGENTS.md

# AGENTS.md

## Project overview
A Next.js app for tracking habits. TypeScript everywhere.

## Build & test
- `npm run dev` — start the dev server
- `npm run build` — production build (must pass before commit)
- `npm test` — run the Vitest suite

## Code style
- Use functional components and hooks
- Prefer named exports
- Run `npm run lint` before finishing

## PR instructions
- Title format: [area] Short description
- All tests and lint must be green

Monorepo tip: drop a nested AGENTS.md inside each package. The AGENTS.md closest to the file being edited takes precedence, and an explicit chat instruction overrides everything. Using Claude Code too? It skips AGENTS.md when a CLAUDE.md exists, so start your CLAUDE.md with @AGENTS.md.

Read the dedicated AGENTS.md guide + generator →

llms.txt — a curated map for AI search

llms.txt is a Markdown file at your site root that gives AI tools a short, hand-picked list of your most useful pages — small enough to fit in a context window. The spec is precise: an H1 with the project name (the only required part), an optional blockquote summary, then H2 sections containing lists of links. By convention, an Optional section holds links that can be skipped when a shorter context is needed.

Example /llms.txt

# Acme Docs

> Acme is an open-source toolkit for building
> data pipelines in Python.

## Docs

- [Quick start](https://acme.dev/start.md): Install and run your first pipeline
- [API reference](https://acme.dev/api.md): Every public class and method

## Examples

- [ETL walkthrough](https://acme.dev/etl.md): A complete end-to-end pipeline

## Optional

- [Changelog](https://acme.dev/changelog.md): Full release history

Not a sitemap: a sitemap lists every page for search engines. llms.txt is the opposite: a deliberately small, curated overview meant to be read at the moment an agent needs information about your site. It is a proposal from Answer.AI (2024, revised as v2 in August 2026), not an official standard. Coding agents use it to find docs; Google says Google Search, including AI Overviews, does not use it.

Want the full spec, a complete annotated example, and a free generator? Read the dedicated llms.txt guide →

Markdown in AI Tools

Markdown shows up at almost every layer of the AI tools you use, from chat replies to agent instructions.

Chat assistants

ChatGPT, Claude, and Gemini render their replies as Markdown — that is where the headings, bold text, and code blocks in their answers come from. Send Markdown in, and the model reads your structure the same way.

Coding agents

Cursor, Copilot, Codex, and Claude Code read Markdown instruction files (AGENTS.md, CLAUDE.md) and write Markdown commit messages, PR descriptions, and docs.

RAG & scrapers

Retrieval pipelines and AI web tools convert HTML to clean Markdown before sending it to a model — it is smaller, structured, and free of navigation and ad noise.

AI search & agents

Google says AI Overviews and AI Mode work from its normal index and ignore llms.txt and Markdown copies, so clear HTML is what counts there. Agents that fetch pages themselves are different: some, like Claude Code, ask for Markdown with an Accept: text/markdown header.

Best Practices

The patterns that make Markdown work well for AI, and the habits to drop.

Lead with a clear heading hierarchy

Avoid

Wall of unstructured text

Headings let the model find the section it needs and weight instructions correctly. # for the top-level goal, ## for sub-tasks.

Put rules and constraints in a bulleted list

Avoid

Bury constraints inside a paragraph

A list of short, parallel bullets is easier for a model to follow item-by-item than the same rules embedded in prose.

Fence code, data, and quoted text

Avoid

Paste code inline with the instructions

Triple-backtick fences, blockquotes, or XML-style tags mark 'this is content, not an instruction'. That reduces mix-ups, though it does not make untrusted input safe from prompt injection.

Use one AGENTS.md, not five tool-specific files

Avoid

Maintain .cursorrules, .windsurfrules, and more in parallel

Most major coding agents read AGENTS.md, and 60k+ open-source projects use it (per agents.md). One file keeps every tool in sync.

Keep llms.txt curated and short

Avoid

Dump every URL like a sitemap

llms.txt is meant to fit in a context window. List only the pages that genuinely help a model understand your site.

Quick Reference

The AI Markdown files at a glance — what to create, where it goes, and who reads it.

File	Location	Read by
README.md	Repository root	Humans first, agents as fallback
AGENTS.md	Repo root + nested per package	Coding agents (Codex, Cursor, Copilot, Jules, Claude Code…)
CLAUDE.md	Repo root and ~/.claude/	Claude Code
llms.txt	Site root (/llms.txt)	AI agents on demand, mostly coding agents (Google Search ignores it)
.cursorrules / .windsurfrules	Repo root	Single-tool (legacy)

Frequently Asked Questions

Why do AI models like ChatGPT and Claude output Markdown?

Partly habit, partly design. Models learn from large amounts of Markdown-formatted text such as READMEs, documentation, and developer forums, so they write it fluently. The chat apps then render it, which is why answers show real headings, lists, and code blocks. It is also an explicit default: OpenAI's Model Spec says that unless told otherwise, assistant output should be formatted in Markdown with LaTeX extensions. Ask for plain text and most models will drop it.

Does using Markdown in my prompt actually improve responses?

Structure helps; Markdown is one good way to add it. A 2024 study (He et al., arXiv 2411.10541) found GPT-3.5's results varied by up to 40% depending on whether the same prompt was written as plain text, Markdown, JSON, or YAML, while GPT-4 was more robust, and no single format won everywhere. OpenAI's GPT-4.1 prompting guide recommends starting with Markdown headings, and Anthropic recommends XML tags for Claude. The gain is largest on long, multi-part prompts; for a one-line question it makes little difference.

What is the difference between AGENTS.md and README.md?

README.md is written for humans: what the project is, how to install it, and how to contribute. AGENTS.md is written for coding agents: the exact build commands, test commands, code-style rules, and conventions an AI needs to make correct changes. Keeping them separate lets the README stay concise while giving agents a predictable place to look for machine-relevant instructions.

What is llms.txt and how is it different from robots.txt or sitemap.xml?

llms.txt is a Markdown file at the root of a website (yourdomain.com/llms.txt) that gives AI agents a short, curated map of your most useful pages. robots.txt tells crawlers what they may access; sitemap.xml lists every indexable page for search engines. llms.txt is a hand-picked summary that an agent reads when it needs information about your site, small enough to fit in a context window.

Is llms.txt an official standard?

No, it is a proposal. Jeremy Howard of Answer.AI introduced it in September 2024 and published a revised v2 in August 2026. Thousands of sites publish one and docs platforms generate it automatically, but it is used mainly by coding agents reading documentation. Google says Google Search, including AI Overviews, does not use it.

Do I need a CLAUDE.md if I already have an AGENTS.md?

Not necessarily. Claude Code reads AGENTS.md on its own, but only when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. If you add a CLAUDE.md, Claude reads that instead and skips AGENTS.md, so start the CLAUDE.md with an @AGENTS.md import and put Claude-only instructions below it. A personal ~/.claude/CLAUDE.md, which applies across all your projects, loads alongside AGENTS.md either way.

How does Markdown save tokens compared to HTML?

Markdown uses one or two characters where HTML uses paired tags: # versus <h1>…</h1>, - versus <li>…</li>. The bigger saving comes from dropping everything else on a real page, such as navigation, scripts, and attributes. Cloudflare measured one of its blog posts at 16,180 tokens as HTML and 3,150 tokens as Markdown, about 80% fewer. On clean, minimal HTML the gap is much smaller.

Should I write my website content in Markdown for AI search?

No. Keep publishing normal HTML. Google says Google Search and its AI features do not use Markdown copies or llms.txt files, and you do not need them to appear there. For AI agents that read sites directly, it can still help to add an llms.txt and .md copies of key pages (page.html.md or page.md), linked with rel="alternate" type="text/markdown". Some agents, such as Claude Code, also request Markdown with an Accept: text/markdown header.

Which AI coding tools read AGENTS.md?

Most of them, including OpenAI Codex, Cursor, GitHub Copilot, Google's Jules, Zed, Amp, Windsurf, Devin, and Claude Code. Gemini CLI and Aider can read it with a one-line setting. Over 60,000 open-source projects use one, according to agents.md. OpenAI contributed the format to the Linux Foundation's Agentic AI Foundation in December 2025, which now stewards it.