AGENTS.md, CLAUDE.md, SKILL.md, llms.txt Explained

There is a quiet pattern behind almost every AI coding tool shipped in the last year: the way you configure the agent is by writing it a markdown file. Not a JSON config, not a YAML pipeline, not a plugin in some SDK — a plain .md document the model reads the way a new teammate reads the onboarding wiki. Four names show up again and again: AGENTS.md, CLAUDE.md, SKILL.md, and llms.txt.

They look similar and they are all markdown, but they do different jobs, are read by different tools, and belong in different places. This is the field guide: what each file is, who reads it, and — the part most explainers skip — where each one should actually live.

TL;DR — Four plain-markdown files now configure most AI agents. AGENTS.md is the vendor-neutral project brief read by 30+ coding tools. CLAUDE.md is Claude Code's own project-instructions file, hierarchical and importable. SKILL.md packages a reusable, on-demand agent capability via progressive disclosure. llms.txt hands AI models a curated map of your website. All four are markdown because an agent is a context engine and the most direct interface is a document it can read. Repo-scoped files live in the repo; durable, cross-repo context belongs in a shared, versioned, agent-readable workspace like MDflow. Start free.

Why markdown is the interface for AI agents

A large language model is a context engine: the quality of what it produces is bounded by the quality of the context you hand it — so the most direct way to configure one is a document it can read verbatim. Markdown is the format that document takes, because it is the rare interface that is legible to humans and natively parseable by models, needs no schema or runtime, and diffs cleanly in version control.

That is why the whole category converged, independently, on the same idea rather than on a config language. Developers sometimes shorthand it as "markdown is the new API for agents": instead of calling functions, you write down what the agent should know and let it read. The four files below are the load-bearing examples, and their combined momentum is real — GitHub's Spec Kit crossed 120,000 stars in months, and AGENTS.md alone is now in the root of tens of thousands of repositories.

AGENTS.md — the vendor-neutral project brief

AGENTS.md is an open, tool-agnostic markdown file at the root of a repository that tells any coding agent how to work in that project: build and test commands, code style, conventions, architecture, and gotchas. Think of it as a README written for the machine instead of the human — the human README explains what the project is; AGENTS.md explains how to operate on it.

Its reach is what makes it matter. AGENTS.md is read natively by 30+ tools — OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, Google Jules, Factory, Aider, Zed, Windsurf, Devin, and more — and appears in over 60,000 repositories. It was formalized as an open specification in August 2025 by OpenAI with Google, Cursor, and Factory, and donated to the Linux Foundation's Agentic AI ecosystem in December 2025, which is what turns it from one vendor's convention into a shared standard.

A minimal AGENTS.md looks like plain prose with headings:

# AGENTS.md

## Setup
- Install: `pnpm install`
- Dev server: `pnpm dev` (port 3000)

## Testing
- Run tests before every commit: `pnpm test`
- Type-check with `pnpm typecheck`

## Conventions
- TypeScript strict mode; no `any`.
- Prefer server components; mark client components explicitly.

There is nothing magic in the syntax — the power is that one file, in a format every agent already reads, replaces the per-tool config files (.cursorrules, .github/copilot-instructions.md, and their cousins) that used to fragment the same information across a dozen vendor-specific dotfiles.

CLAUDE.md — Claude Code's project instructions

CLAUDE.md is the instruction file Anthropic's Claude Code reads automatically to learn a project's commands, conventions, and constraints — the same job as AGENTS.md, but Claude-specific and with two extra powers: hierarchy and imports. It is loaded at the start of a session and its contents are treated as high-priority standing instructions.

Two features distinguish it from a plain brief:

• Hierarchy. Claude Code merges CLAUDE.md files from several levels — a global ~/.claude/CLAUDE.md for your personal defaults, a project-root file checked into the repo for team-wide rules, and per-subdirectory files for module-specific guidance. The closest file wins where they conflict, so a monorepo can carry one root policy and refine it per package.
• Imports. A CLAUDE.md can pull in other files with an @path reference, so you can keep the canonical rules in one place and include them where needed — including pointing CLAUDE.md at a shared AGENTS.md so the two never drift.

Because Claude Code also reads AGENTS.md, the common 2026 setup is: keep the canonical, portable instructions in AGENTS.md, and use CLAUDE.md only for Claude-specific behavior (or a one-line @AGENTS.md import). You get vendor-neutral portability and Claude's niceties without maintaining two copies of the same conventions.

SKILL.md — a reusable capability the agent loads on demand

SKILL.md is the entry file of an Anthropic Agent Skill: a folder that bundles instructions, and optionally scripts and reference files, into a capability an agent can discover and load only when a task needs it. Where AGENTS.md and CLAUDE.md are standing context loaded every session, a skill is conditional context — it stays out of the way until it is relevant.

The file itself is simple: YAML frontmatter with a required name and description, then a markdown body of instructions.

---
name: pdf-form-filler
description: Fill and flatten PDF forms from structured data. Use when
  the user asks to complete, sign, or populate a PDF form.
---

# Filling PDF forms

1. Read the field map with `scripts/inspect.py <file.pdf>`.
2. Match user data to field names.
3. Fill and flatten with `scripts/fill.py` ...

What makes skills scale is progressive disclosure, a three-tier loading model:

1. Startup: the agent reads only the name + description of every installed skill — about 100 tokens each. Just enough to know when a skill applies, without loading it.
2. Activation: when the task matches, the agent loads the full SKILL.md body (recommended under ~5,000 tokens) into context.
3. On demand: larger reference files, templates, or scripts in the skill folder are read only if the body points to them.

That keeps an agent's working context lean even when it has hundreds of skills available — it pays the token cost of a capability only at the moment it uses it. The description is the load-bearing field: it is the only thing the model sees at startup, so it must state both what the skill does and when to use it. The format has spread beyond Claude into a broader open convention for packaging agent skills.

llms.txt — a map of your website for AI models

llms.txt is a markdown file at the root of a website (/llms.txt) that gives AI models a curated, LLM-friendly map of the site: a short description of what the site is, then links to the pages that matter, ideally with plain-markdown versions. Where the other three files configure an agent working in a repo, llms.txt configures how an AI model reads your published site.

It was proposed by Jeremy Howard of Answer.AI in September 2024, to solve a concrete limitation: a model's context window cannot hold an entire website, and rendered HTML is mostly navigation, ads, and markup noise. Rather than make the model crawl and guess, llms.txt points it straight at the signal. A companion llms-full.txt goes further and embeds the actual content of those pages so an agent can ingest everything in one fetch.

# MDflow

> A hosted markdown workspace your AI agents can read and write over MCP and an HTTP API.

## Docs
- [MCP server](https://mdflow.cz/docs/mcp.md): connect Claude, ChatGPT, Cursor
- [HTTP API](https://mdflow.cz/docs/api.md): REST endpoints and auth

## Blog
- [Spec-driven development](https://mdflow.cz/blog/spec-driven-development-markdown-specs.md)

Adoption accelerated when Mintlify shipped llms.txt for every docs site it hosts in late 2024 — Anthropic, Cursor, Vercel, Supabase, and thousands of others gained the file overnight. It is now a standard part of making documentation and marketing content legible to AI answer engines, and it pairs naturally with the convention of serving any page as plain markdown by appending .md to its URL.

The four at a glance

The through-line: all four are markdown, all four are read rather than executed, and each answers a different "how should the agent behave here?" — in this repo (AGENTS.md / CLAUDE.md), for this task (SKILL.md), on this website (llms.txt).

Which files each project needs

Not every project needs all four. A useful rule of thumb:

1. Any repo an agent touches → an AGENTS.md (and a CLAUDE.md that imports it if you use Claude Code). This is the highest-leverage file; write it first.
2. A repeatable workflow your agent does often — filling forms, running a release, applying a house style → package it as a skill with a SKILL.md.
3. Any public website or docs site you want AI models and answer engines to read accurately → an llms.txt (and .md twins of key pages).
4. A team with shared standards, decisions, or vocabulary across many repos → a home for the durable context that none of the repo-local files can own alone. More on that next.

How MDflow fits

Three of these files are repo-scoped and belong exactly where they are — but the moment your standards, skills, and decisions need to be shared across many repos and agents, a file buried in one repository stops being the right home. MDflow is the shared, versioned, agent-readable place that context can live.

What already lines up today

MDflow speaks the same format these files do. Documents are stored as markdown-native files — the exact format AGENTS.md, CLAUDE.md, SKILL.md, and llms.txt all use. Context written in MDflow is the same artifact an agent reads; there is no export step and no proprietary wrapper.

MDflow already ships all four discovery surfaces for itself. MDflow publishes its own /llms.txt, an agent card, an OpenAPI spec, and raw .md twins of every page — it practices the convention it is describing, which is why an AI model can read this very post at /blog/agents-md-claude-md-skill-md-llms-txt.md.

Folder descriptions turn a workspace into agent context. Each folder in MDflow has a description that states what its documents are for — the same instinct as an AGENTS.md, applied to a knowledge base. Put your coding standards in a "Engineering standards" folder and your architecture decisions in an "ADRs" folder, describe each accurately, and mdflow_get_context ranks those folder descriptions first when an agent asks for "our API conventions" — returning the right document, not your whole workspace. It is retrieval without a vector database.

Agents read and write over MCP and an HTTP API. Over MDflow's remote MCP server, Claude and the ChatGPT app connect with an OAuth sign-in (no token to paste), while Claude Code, Cursor, and Codex authenticate with a Personal Access Token. So the same agent that reads your AGENTS.md in the repo can pull the shared standards doc from MDflow as context — and write a proposed update back.

Version history and raw .md twins. Every change is version-tracked, so when a teammate or an agent revises the shared standard, the diff is there. And every document has a raw .md twin over open CORS, so any tool, CI job, or agent that can fetch a URL reads the canonical version — the same "serve it as markdown" idea that makes llms.txt and .md twins work, applied to your private workspace.

The split is clean: AGENTS.md, CLAUDE.md, and SKILL.md stay in the repo; llms.txt stays at your site root; and the durable, cross-cutting context they all gesture at — standards, decisions, glossaries, reusable skills — lives in one shared workspace every agent can reach.

Where we are headed

This is direction, not a dated commitment: serving a whole collection of related context to an agent as one cross-linked bundle (standards + ADRs + glossary, retrieved together); richer typed frontmatter so shared docs carry status, owner, and version as structured metadata the way SKILL.md frontmatter does; and tighter round-trips for agent-proposed changes a human reviews before they land.

The bottom line

The way you program an AI agent in 2026 is, increasingly, to write it a markdown file. AGENTS.md briefs any coding tool on your repo. CLAUDE.md does the same for Claude Code, with hierarchy and imports. SKILL.md packages a capability the agent loads only when it is needed. llms.txt hands AI models a map of your website. Four files, one insight: an agent is a context engine, and markdown is the most direct way to give it context.

Keep the repo-scoped files in the repo. But the standards, decisions, and skills that many repos and many agents share need a home that is versioned and agent-readable — and that is what MDflow is built to be: markdown-native storage your agents already understand, folder descriptions that act as retrieval context, read-and-write access over MCP and an HTTP API, version history on every change, and raw .md twins any tool can fetch.

Start free · Connect an AI agent · Read the API docs

Frequently asked questions

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

Both are plain-markdown instruction files that tell a coding agent how a project works — build commands, test commands, conventions, architecture. AGENTS.md is a vendor-neutral open standard read by 30+ tools including Codex, Cursor, Copilot, and Gemini CLI; it was donated to the Linux Foundation in December 2025. CLAUDE.md is Anthropic Claude Code's own file, which loads hierarchically (global, project, subfolder) and can import other files with @path syntax. Claude Code also reads AGENTS.md, so many teams keep one canonical AGENTS.md and point CLAUDE.md at it.

What is SKILL.md?

SKILL.md is the entry file of an Anthropic Agent Skill — a folder that packages instructions, scripts, and resources an agent can load on demand. It has YAML frontmatter (a required name and description) plus a markdown body of instructions. It works by progressive disclosure: the agent reads only the ~100-token name and description at startup, loads the full body when the skill is relevant, and pulls linked reference files only when needed.

What is llms.txt used for?

llms.txt is a markdown file at a website's root (/llms.txt) that gives AI models a curated, LLM-friendly map of the site — a short description plus links to the important pages, ideally with plain-markdown versions. Proposed by Jeremy Howard of Answer.AI in September 2024, it solves the problem that a model's context window cannot hold an entire website, so it points the model at what matters instead of making it crawl rendered HTML.

Why are AI agents configured with markdown files instead of code or JSON?

Markdown is readable by both humans and models, needs no parser or schema, and diffs cleanly in Git. An agent is a context engine, so the most direct way to steer it is a document it can read verbatim. That is why the whole category — AGENTS.md, CLAUDE.md, SKILL.md, llms.txt — converged on plain markdown rather than a config language, a pattern often summarized as "markdown is the new API" for agents.

Where should these markdown files live?

Repo-scoped files belong in the repository beside the code they describe: AGENTS.md and CLAUDE.md at the repo root, SKILL.md inside a skills folder, and llms.txt at your website root. Durable, cross-cutting context that many repos and agents share — product standards, architecture decisions, glossaries, reusable skills — outlives any single repo and is better kept in a shared, versioned, agent-readable markdown workspace like MDflow.

Further reading

• Answer.AI — The /llms.txt proposal and the llms.txt spec
• OpenAI — AGENTS.md open specification
• Anthropic — Equipping agents for the real world with Agent Skills and the Agent Skills docs
• GitHub — Spec Kit
• MDflow — Spec-Driven Development: Where Your Markdown Specs Should Live · Folder Descriptions as Agent Context · Letting AI Agents Write Back to Your Knowledge Base · MCP documentation · API documentation