AGENTS.md, CLAUDE.md, .cursorrules: what format your AI reads and how to set it up

## Why there are several formats and what to do about it

Until August 2025, the picture looked like this: Cursor wanted .cursorrules, Claude Code - CLAUDE.md, GitHub Copilot - .github/copilot-instructions.md, Aider - CONVENTIONS.md. The serious project supported five almost identical files so that each agent worked normally.

In August 2025, OpenAI proposed AGENTS.md as a vendor-neutral standard. In December 2025, the format was transferred to the Linux Foundation along with the Model Context Protocol. By May 2026, AGENTS.md is natively read by all major agents and is used in 60,000+ public repositories.

But the old formats are alive - and everyone has a reason to exist.

## Five formats: how different

### AGENTS.md is a universal standard

The simplest and most compatible. Markdown file at the root of the repository without the required structure. Cursor, Claude Code, GitHub Copilot, Gemini CLI, Aider, Windsurf, Zed and 20+ agents.

The nearest-file-wins principle: You can put AGENTS.md at the root for global rules, and separate AGENTS.md at the subfolder for packet rules. OpenAI holds 88 such files in its mono repository.

When to use: if the team has different tools, if the project is open-source, if you need one source of truth for everyone.

### Claude.md – for Claude Code with memory

Same as AGENTS.md, but with a three-level memory model:

• ~/.claude/CLAUDE.md - personal preferences, work on all projects on the machine
• ./CLAUDE.md at the root of the project - command file, commits to git
• ./CLAUDE.local.md - personal edits for the project, in .gitignore

Plus, Claude Code himself writes notes about the project in ~/.claude/projects/<project>/memory/ during the work. It's separate from the Claude.md you write.

Anthropic recommends direct imperatives instead of descriptions. "Never use inline moki - use src/test/factories/*" works better than "we usually avoid inline moks." The markers IMPORTANT, YOU MUST, NEVER statistically increase the accuracy of following the rules. It is better to keep the file up to 200 lines long and important rules start to get lost.

When to use: if you work primarily with Claude Code and want to have personal + command + local rules separately.

### .cursor/rules for Cursor with glob activation

Cursor was the first to add conditional rule activation. Files live in .cursor/rules/<название>.mdc with YAML frontmatter:

-
description: Rules for the GraphQL layer
globs:
- "src/graphql/**/*.ts"
alwaysApply: false
-

Four activation modes: always, by glob file pattern, by agent decision, manually. This is the most flexible format of all, but only for Cursor. The other instruments don't read it.

When to use: if Cursor is the main tool and you need rules that are included only when working with specific files. In conjunction with AGENTS.md is rooted for other agents.

### SKILL.md – task context on demand

A fundamentally different format. Not a constant context, but a packaged expertise that loads when the task matches the description.

-
name: design-system-tokens
description: |
Creates, verifies and documents design system tokens.
Use when a user talks about tokens, colors,
typography, indentations or components.
-

# Token rules

All colors in CSS variables in `app/globals.css`
Never create new components if you have an existing one.
-.

The frontmatter is the loading part. description is what Claude reads to decide whether to include a skill. The body of the file is read only after activation. One skill per task, the body rules, not complete documentation.

When to use: for packaging a specific expertise – design system tokens, component patterns, publication rules.

### .cursorrules is an outdated Cursor format

The predecessor of .cursor/rules/. Cursor is still reading it, but it’s best to start with the MDC format in .cursor/rules/. Other tools ignore it.

## DESIGN.md - a separate story for designers

All formats above answer the question “how to work with code”. DESIGN.md answers another question: “What does this product look like?”.

The format was invented by Google Stitch - Stitch generates it as an artifact of the design system and transmits it to agents. In April 2026, Google launched the Apache 2.0 specification. It’s now being read by Stitch, Claude Code, Cursor, v0, and any other tool you want to support.

DESIGN.md contains machine-readable tokens in YAML and human-readable explanations for why such solutions are:

#Colors
primary: "#1A1A2E"
accent: "#E94560"
surface: "#F5F5F0"

The color system is based on the contrast of a dark background and a warm accent.
Neutral surface color is used for cards and sections.

##Typography
display: "Fraunces"
body: "Bricolage Grotesque"
mono: "JetBrains Mono"

Do not use: Inter, Roboto, Open Sans.

##DoNo
- Purple blue gradients
Glassmorphism without functional meaning
Create new button options – use existing ones

The difference between DESIGN.md and CLAUDE.md with design rules: CLAUDE.md tells you how to work, DESIGN.md tells you how to look. In practice, designers often keep both - DESIGN.md with visual rules and AGENTS.md or CLAUDE.md with working conventions.

Repo awesome-claude-design on GitHub collected 68 ready-made DESIGN.md for well-known brands - from Notion to Stripe. 71,000 stars in the weeks after launch. It’s not an installation – just put the right file at the root of the project and AI works in that style.

## What to write specifically to a designer

The content depends on the format, but the logic is the same: specific rules, not wishes.

** For AGENTS.md / CLAUDE.md - working rules:**

## Components
Use existing components by the name Button/Primary, Card/Default
Never create a new component if you already have one.
- Name new components according to the scheme: [Category]/[Option]

## Files
All CSS variables in `app/globals.css` only
- Don't touch `src/lib/billing/*`

## Forbidden
- Inter, Roboto, Open Sans, Arial
Inline styles – CSS variables and Tailwind classes only
- Purple-blue gradient on a white background

** For SKILL.md, design as a skill:**

-
name: brand-design-system
description: |
Brand rules and design systems. Use it at work.
with UI, components, tokens, colors, typography.
-

#Tokens

| Token | Value | Use |
|------|-------|------------ |
| --color-primary | #1A1A2E | Backgrounds, CTA |
| --color-accent | #E94560 | Accents, hover |
| --font-display | Fraunces | Headings H1-H2 |
| --font-body | Bricolage Grotesque | Main text |

Tables instead of prose are denser in tokens, the model reads faster.

## Three Errors That Kill the Meaning of These Files

Write wishes instead of rules. “Use beautiful typography” AI will ignore – it has no concept of “beautiful”. "Never use Inter, Roboto, Open Sans" is a specific limitation that works. Every rule must be verifiable: either done or not.

Make a file too long. Anthropic writes directly in the documentation: If CLAUDE.md is too long, important rules are lost in noise. 200 lines is a guide for a single file. If you need more – break into several SKILL.md by topic, each download only when needed.

Write once and forget. Tools change, components are added, tokens are renamed. A file that hasn’t been updated for three months is starting to conflict with real code — and AI is running by outdated rules. Once a quarter is enough: read, remove irrelevant, add new.

## Which file to start first

● You work at Cursor and don’t plan anywhere else → .cursor/rules/ + AGENTS.md
● Working with Claude Code → CLAUDE.md (+ CLAUDE.local.md for personal use)
● The team has different tools → AGENTS.md as the basis
● Want to pack a design system → SKILL.md for tokens and rules
● Want visual unity between sessions → DESIGN.md next to AGENTS md

Realistic minimum to start: one AGENTS.md with forbidden fonts, component names and a list of folders that can not be touched. It takes 20 minutes and works in all instruments at once.