AGENTS.md, CLAUDE.md, SKILL.md and Cursor rules: which file does what

By markdownregistry. Published October 2, 2026. Updated October 2, 2026.

AGENTS.md and CLAUDE.md hold a project's standing instructions; SKILL.md defines one skill an agent loads only when a task needs it; Cursor rules are Cursor's own instruction files; DESIGN.md describes a design system; and llms.txt maps a website's documentation for AI models. Which agent reads which file is set by each agent's documentation, so every claim below links the page it comes from. The counts come from the registry's own crawl of public GitHub, State of agent markdown, September 2026.

Every claim about another tool was checked against that tool's own documentation on October 2, 2026. Figures are from State of agent markdown, September 2026, data frozen September 27, 2026.

SKILL.md vs AGENTS.md vs CLAUDE.md: which file does what?

AGENTS.md and CLAUDE.md do the same job: they hold a project's standing instructions, what an agent should know before it changes any code, such as how to build and test and which conventions to follow. AGENTS.md is the shared name that many coding agents read, including Codex, Cursor and GitHub Copilot; CLAUDE.md is Claude Code's own file. SKILL.md is different: it defines one skill, a folder of instructions and optional scripts that an agent reads only when a task calls for it, so an agent can carry many skills without filling its context.

AGENTS.md vs CLAUDE.md: what is the difference, and do I need both?

The difference is who reads them. AGENTS.md is an open format, now stewarded by the Agentic AI Foundation under the Linux Foundation, that many coding agents read; CLAUDE.md is the file Claude Code reads. You need only one of them if every agent your team uses reads it. If you use Claude Code alongside other agents, write the instructions once in AGENTS.md: Claude Code reads AGENTS.md when the project has no CLAUDE.md, and if you want a CLAUDE.md as well, give it the line @AGENTS.md so it imports the shared file instead of repeating it.

Claude Code reads a CLAUDE.md in place of AGENTS.md when both exist, and its docs list a few places where the two still behave differently, such as InstructionsLoaded hooks, which fire for CLAUDE.md and not for an AGENTS.md read on its own (Claude Code: where AGENTS.md differs). In the registry's crawl there are 3,901 AGENTS.md files and 2,081 CLAUDE.md files.

Does Claude Code read AGENTS.md if there is no CLAUDE.md file?

Yes, from Claude Code version 2.1.277. By default it reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any directory above it; when there is one, it reads the CLAUDE.md files instead. Your personal ~/.claude/CLAUDE.md does not count for that check. To have it read both, set Project instructions to claude-md-and-agents-md in /config. Older versions, and some sessions before version 2.1.281 such as those on Amazon Bedrock or with telemetry disabled, read CLAUDE.md only, so in those sessions give Claude Code your AGENTS.md through a CLAUDE.md that contains the line @AGENTS.md.

It does not read AGENTS.local.md, AGENTS.override.md or anything under .agents/. A CLAUDE.local.md counts as a CLAUDE.md here, so adding one for your own notes stops Claude Code reading AGENTS.md unless you choose claude-md-and-agents-md. Source: Claude Code docs, AGENTS.md.

How do I keep AGENTS.md and CLAUDE.md in sync in the same repo?

Keep the instructions in one file and point the other at it. Write them in AGENTS.md, and make CLAUDE.md a file whose first line is @AGENTS.md, an import Claude Code expands, with any Claude-only instructions below it. A symlink made with ln -s AGENTS.md CLAUDE.md also works, but Claude Code's docs advise the import if anyone clones the repository on Windows, where a committed symlink can check out as a one-line text file. Two copies of the same text drift apart; an import cannot.

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

That is the example from Claude Code's docs. Run /context in the next session and check that CLAUDE.md appears under Memory files. Of 1,203 folders in the registry's crawl of public GitHub that hold both files, 347 (28.8%) use this import and 426 (35.4%) keep two separate files; our count of what those folders do has the rest. These files change often: in the registry's crawl, at least 27.8% (730 of the 2,623 first indexed at least 14 days before the data was frozen) got an upstream commit dated within 14 days after first indexing for AGENTS.md, and for CLAUDE.md at least 23.2% (309 of the 1,333 first indexed at least 14 days before the data was frozen) got an upstream commit dated within 14 days after first indexing, each a lower bound.

Cursor rules vs AGENTS.md: which one should I use for my repo?

Use AGENTS.md when plain instructions are enough or when more than one agent works in the repository: Cursor reads AGENTS.md in the project root and in subdirectories, and so do many other agents. Use Cursor rules, .mdc files in .cursor/rules, when you need what only they do: a rule applied only when matching files are in context, one the agent pulls in when its description is relevant, or one used only when you mention it. Cursor ignores a plain .md file in .cursor/rules, because the rule's frontmatter is what tells Cursor when to apply it.

A rule's frontmatter decides when it applies: alwaysApply: true for every chat, globs for matching files, a description for the agent to judge, or none of them for an @-mention only (Cursor docs, Rules). The registry indexes 510 Cursor rules files, both .cursor/rules/*.mdc and .cursorrules; browse them at Cursor rules. Which rule types projects actually use, and the setting that makes Cursor ignore a rule's file pattern, are counted in how projects write Cursor rules.

What is a CLAUDE.md file in Claude Code?

A CLAUDE.md file is a markdown file of standing instructions that Claude Code reads at the start of every session: build and test commands, conventions, project layout, and rules that hold in every session. A project's file lives at ./CLAUDE.md or ./.claude/CLAUDE.md and is committed for the whole team; ~/.claude/CLAUDE.md holds your own instructions for every project, and CLAUDE.local.md your own for one project. A CLAUDE.md in a subfolder loads when Claude Code reads files in that folder. Run /init to generate a first version from your codebase.

To start one, this CLAUDE.md template marks what to change for your project. Claude Code's docs suggest adding to it when Claude makes the same mistake twice or when you retype the same correction, and moving multi-step procedures into a skill instead (Claude Code docs, memory). Real examples: 2,081 CLAUDE.md files from public GitHub, most-starred repositories first.

How to write a good AGENTS.md file for my repository

Put AGENTS.md at the repository root and write what a new teammate would need before changing code: a project overview, the exact build and test commands, code style, testing instructions and security notes, the sections agents.md suggests. Keep it to facts that hold for every task, and keep it short: Codex stops adding project instructions once they reach 32 KiB combined, by default. In a monorepo, put another AGENTS.md inside each package that needs one; agents read the nearest file, so the closest one wins.

Agents run the commands you list, so write them exactly as they should be typed. To start from a file with each section explained, use this AGENTS.md template, which says what to change in it. In Codex, an AGENTS.override.md in a directory replaces that directory's AGENTS.md (Codex docs). To read what others wrote, the registry lists 3,901 AGENTS.md files from public GitHub, most-starred repositories first, each with its version history.

What is DESIGN.md and how do AI coding agents use it?

DESIGN.md is a markdown file that describes a project's visual design system so coding agents build interfaces that match it. The format published by Google Labs puts exact design tokens, such as colors, type and spacing, in YAML front matter and explains in prose why they exist and how to apply them; its own repository marks it as an alpha version. An agent uses it as it uses any instruction file, by reading it. None of the agent docs linked on this page says it loads DESIGN.md on its own, so point to it from a file your agent does load, for example an @DESIGN.md line in CLAUDE.md, which Claude Code expands.

The format's repository ships a linter: npx @google/design.md lint DESIGN.md (google-labs-code/design.md). The registry indexes 1,042 DESIGN.md files with every version it has recorded, at DESIGN.md files. Many are templates: 53.3% (555) are at least 200 bytes and byte-identical to a file in another repository, and 540 of those copies sit in the four repositories holding the most.

How the files in the registry fare against that linter is counted in DESIGN.md files against the official linter: most hold no tokens at all.

How to add an llms.txt file to my website

Publish a markdown file at /llms.txt on your site. The llms.txt proposal asks for an H1 with the site or project name, which is the only required part, then a blockquote with a short summary, optional paragraphs, and sections under H2 headings that list links to the pages a model should read, each written [name](url) with an optional note after a colon. A file can also sit at a subpath such as /docs/llms.txt and cover the pages under it. The proposal also suggests serving a clean markdown copy of each page at the same URL with .md added.

# Project name

> One or two sentences on what the project is.

## Docs

- [Quick start](https://example.com/start.md): install and first run

## Optional

- [Changelog](https://example.com/changelog.md)

The Optional section is, by convention, for links an agent can skip when it needs a shorter context (llmstxt.org).

How closely real files follow this shape is counted in how llms.txt files follow the format: most get the H1 and summary right, and fewer keep their H2 sections as lists of links.

Where can I find llms.txt examples from real websites?

The llms.txt proposal points to three from the AI labs' own developer docs: OpenAI at developers.openai.com/llms.txt, Anthropic at docs.anthropic.com/llms.txt (which now redirects, through platform.claude.com/docs/llms.txt, to platform.claude.com/llms.txt) and Google's Gemini at ai.google.dev/gemini-api/docs/llms.txt. For more, the registry indexes llms.txt and llms-full.txt files committed to public GitHub repositories, with each version it has recorded; a file in a repository may differ from what a website serves.

Open the three: OpenAI, Anthropic, Gemini. The registry's 415 llms.txt files change faster than any other kind it tracks: at least 41.2% (106 of the 257 first indexed at least 14 days before the data was frozen) got an upstream commit dated within 14 days after first indexing, a lower bound.

Where can I search real CLAUDE.md files from popular GitHub repos?

markdownregistry indexes CLAUDE.md files from public GitHub repositories, along with AGENTS.md, SKILL.md, Cursor rules, DESIGN.md and llms.txt files, and lists each kind with the most-starred repositories first. Every file keeps each version the registry has recorded, with a diff between versions and an audit grade, and the search page covers all of them. When its report was frozen on September 27, 2026, it held 2,081 CLAUDE.md files, 3,901 AGENTS.md files, 510 Cursor rules, 1,042 DESIGN.md files and 415 llms.txt files.

Browse by kind: CLAUDE.md · AGENTS.md · SKILL.md (61,170) · Cursor rules · DESIGN.md · llms.txt, or search all of them. The registry finds repositories through GitHub topic and README searches, so this is its crawl, not every file on GitHub.

Sources

• Claude Code docs: CLAUDE.md, AGENTS.md and imports
• AGENTS.md
• Cursor docs: Rules
• Codex docs: AGENTS.md
• GitHub docs: repository custom instructions for Copilot
• google-labs-code/design.md
• llmstxt.org: the llms.txt proposal
• Agent Skills specification

Last checked October 2, 2026.

Read next

• Where to find agent skills: directories, marketplaces and package managers
• SKILL.md format: the required frontmatter fields, and skills vs MCP
• Every SKILL.md skill in the registry, most starred first
• State of agent markdown, September 2026

Try it

npx modelranch add anthropics/skills/pdf

That installs one skill pinned to its exact version. Every way to install the CLI is on the mdr CLI page.