AGENTS.md vs CLAUDE.md vs Cursor Rules vs Copilot (2026)

For most of 2024 and 2025, every AI coding tool invented its own way to tell the agent how your codebase worked. Cursor wanted a .cursorrules file. Claude Code wanted a CLAUDE.md. GitHub Copilot wanted .github/copilot-instructions.md. Aider wanted a CONVENTIONS.md. By mid-2025 a serious open-source codebase needed five near-identical files to keep every agent happy.

That fragmentation broke in August 2025, when OpenAI proposed AGENTS.md as a vendor-neutral convention. In December 2025 it was donated to the Linux Foundation's new Agentic AI Foundation alongside the Model Context Protocol. By May 2026, AGENTS.md is read natively by every major coding agent and ships in 60,000+ public repositories.

But the older conventions did not disappear. CLAUDE.md is still richer than AGENTS.md for Claude Code users. Cursor's MDC rules still beat AGENTS.md for glob-scoped activation. SKILL.md does something no one else does. This article compares the five formats that matter in 2026, line by line, and tells you which to adopt.

What is an agent steering file?

An agent steering file is a markdown document committed to your repository that an AI coding agent reads automatically before generating code. It is the agent equivalent of a README: not for humans browsing the project, but for an LLM that has been dropped into your codebase with no context and needs to know how you build, test, name things, and ship.

The contents are conventional but converge on the same eight or so sections: project overview, build and test commands, code style, naming conventions, file layout, framework-specific gotchas, security and secrets handling, and a do-not-touch list. The point is that this lives in the repo (so it is versioned with the code), is plain markdown (so any future tool can parse it), and lives in a predictable location (so the agent does not have to be told where to look).

For a fuller treatment of why this pattern emerged and what belongs inside one, see our AGENTS.md complete guide. For the broader landscape of agents that consume these files, see our AI coding agents complete guide.

What are the five steering-file formats today?

As of May 2026, these are the live conventions you will see in real-world repositories:

Two of those five (AGENTS.md, SKILL.md) are designed as open standards. The other three are vendor conventions that happen to look similar. The deprecated .cursorrules single-file format is still readable by Cursor but produces no warnings if you migrate away.

How does AGENTS.md work?

AGENTS.md is the simplest of the five and explicitly the lowest-common-denominator. The spec is one sentence long: a plain markdown file at AGENTS.md in your repository root, with no required structure or frontmatter. Agents parse it as natural language.

# AGENTS.md

## Build & test
- `pnpm install` then `pnpm dev` for the app at :3000
- `pnpm test` runs vitest + playwright
- CI is `.github/workflows/ci.yml`; do not edit without approval

## Code style
- TypeScript strict mode; no `any` without a `// TODO(types):` comment
- Functional React components; no class components
- styled-components for marketing pages, Tailwind v4 for `/app/*`

## Do not touch
- `src/lib/billing/*` (PCI scope)
- `pages/api/webhooks/*` (signed payloads)

The deliberate minimalism is the feature. Because there is no schema, every tool can read it and every contributor can write it. OpenAI's own monorepo ships 88 separate AGENTS.md files at last count, one per significant package, with the nearest-file-wins rule giving each package its own scope.

How does CLAUDE.md work?

CLAUDE.md is what AGENTS.md would look like if you optimised it for one agent and added a memory hierarchy. Like AGENTS.md, it is plain markdown with no required frontmatter. Unlike AGENTS.md, Claude Code loads it from three locations and merges them:

• User-level: ~/.claude/CLAUDE.md — your personal preferences, applies to every project on your machine.
• Project-level: ./CLAUDE.md at the repo root — committed to git, shared with the team.
• Local-only: ./CLAUDE.local.md — gitignored, your private overrides for this project.

Nested CLAUDE.md files in subdirectories are not loaded at startup but are pulled into context when Claude reads files in that subtree. Anthropic also runs an auto-memory layer where Claude writes notes about your project to ~/.claude/projects/<project>/memory/ over time, separately from the human-authored CLAUDE.md.

The recommended style is direct imperatives, not observations: write "never use inline mocks — use src/test/factories/*" rather than "we generally avoid inline mocks." Anthropic's own docs confirm that emphasis markers (IMPORTANT, YOU MUST, NEVER) measurably increase adherence. The Claude team also recommends keeping each file under roughly 200 lines, with subagents handling the rest. Our Claude Opus 4.7 guide covers the full context model.

How do Cursor's .cursor/rules work?

Cursor was the first mainstream tool to add conditional, frontmatter-driven activation to its steering files. The current format (which deprecated the older .cursorrules single-file in late 2024) lives at .cursor/rules/<name>.mdc:

---
description: Conventions for the GraphQL layer (resolvers, schema, codegen)
globs:
  - "src/graphql/**/*.ts"
  - "src/server/resolvers/**/*.ts"
alwaysApply: false
---

# GraphQL conventions
- All resolvers live in `src/server/resolvers/`
- Run `pnpm codegen` after schema changes
- Never throw raw errors; use `GraphQLError` with a typed `extensions.code`

The three frontmatter fields combine into four activation modes:

• Always: alwaysApply: true — attached to every request.
• Auto-attach: alwaysApply: false + globs — attached only when the agent is editing matching files.
• Agent-decided: alwaysApply: false + description with no globs — the agent reads the description and decides whether to pull in the rule.
• Manual: invoked explicitly by the user with @rule-name.

This is the most expressive of the five formats but also the most Cursor-locked: nothing else reads .mdc. The pragmatic answer for Cursor users in 2026 is to keep an AGENTS.md at the root (so every other agent works) and use .cursor/rules/ for scoped overrides where Cursor's auto-attach is genuinely useful. See our Cursor IDE guide for the rest of the workflow.

How does Anthropic's SKILL.md format work?

SKILL.md solves a different problem from the other four. AGENTS.md, CLAUDE.md, Cursor rules, and Copilot instructions are persistent context — they apply to every interaction in the project. SKILL.md is task-scoped: a self-contained capability that the agent invokes only when its description matches the current task.

---
name: ghost-publish
description: |
  Publish a markdown article to Ghost via the Admin API. Use when the
  user asks to publish, draft, or post an article to the blog.
---

# Ghost publish skill

Steps:
1. Read the article JSON from the path the user provided.
2. Validate required fields: title, html, status.
3. POST to `$GHOST_URL/ghost/api/admin/posts/` with a JWT in the Authorization header.
4. Verify the returned URL with a 200-check.

The frontmatter is the load-bearing part. name is a lowercase-kebab identifier (max 64 chars, no "anthropic" or "claude" reserved words). description (max 1024 chars) is what Claude actually reads to decide whether to invoke the skill — it must say both what the skill does and when to use it. The body of the file is only read once the skill is selected.

A skill directory can also bundle scripts, reference docs, and assets next to SKILL.md. This makes skills closer to a tiny package than a markdown rule. The format is open: any agent could implement the same convention, though as of mid-2026 only Anthropic's products do.

How does GitHub Copilot's instructions file work?

GitHub Copilot's variant is the closest to AGENTS.md in spirit but lives at a fixed path: .github/copilot-instructions.md. It is plain markdown, repo-wide, no frontmatter required.

# .github/copilot-instructions.md

We use TypeScript with strict mode enabled. Never use `any`; widen to `unknown`
and narrow with a type guard.

React components are functional. Use `useReducer` over `useState` when state
has more than two fields.

For database access, always go through `src/db/client.ts`. Never import the
`pg` driver directly.

For path-scoped variants, Copilot reads .github/instructions/*.instructions.md files with YAML frontmatter containing a description and an applyTo glob — close to Cursor's MDC format but in a Copilot-specific location. Microsoft's own guidance is to keep each instruction short and self-contained, include the reasoning behind each rule, and skip anything a linter would already catch.

How do these formats handle monorepos?

All five formats now have a story for monorepos, but they take different routes:

• AGENTS.md: nearest-file-wins. Place an AGENTS.md at the root for global defaults, then drop additional AGENTS.md files in packages/api/, packages/web/, services/billing/. When the agent edits a file, it walks up the directory tree and uses the closest one. OpenAI's monorepo has 88 such files.
• CLAUDE.md: similar nearest-file-wins for nested CLAUDE.md, plus the three-layer global/project/local hierarchy.
• .cursor/rules: glob-driven. Instead of nesting, you put all rules in .cursor/rules/ and let globs: patterns scope them. A backend.mdc with globs: services/api/** behaves like a nested file but lives centrally.
• SKILL.md: not a monorepo concern. Skills live in user or project skill directories and apply across the whole repo by activation, not by file path.
• .github/copilot-instructions.md: single file at .github/, with .github/instructions/*.instructions.md for path scoping via the applyTo glob.

In practice, AGENTS.md's nested model has won by adoption: it requires no schema knowledge, the file lives next to the code it documents, and every modern agent honours nearest-file-wins.

Which steering file wins for which use case?

Use this as a decision matrix:

The honest 2026 default is: start with AGENTS.md, add Cursor MDC rules only if you hit a real scoping limitation, and add CLAUDE.md only if your team standardises on Claude Code. The other formats are useful but not load-bearing for most teams.

What conventions are still emerging?

Three things to watch over the next year:

• Frontmatter on AGENTS.md. The base spec is frontmatter-free, but proposals exist for an optional YAML block with fields like scope, priority, and applies_to. The Linux Foundation working group has not adopted them, partly because keeping AGENTS.md frontmatter-free is what made adoption easy.
• Cross-tool skill registries. SKILL.md is open, but only Claude reads it today. Expect Cursor, Copilot, and Codex to either adopt SKILL.md or propose a parallel skills standard through the AAIF.
• Auto-generated agent files. Several tools (Cursor's /Generate Cursor Rules, Anthropic's /init) now scaffold an AGENTS.md or CLAUDE.md by reading the codebase. A February 2026 ETH Zurich study (Evaluating AGENTS.md, arXiv 2602.11988) built AGENTbench from 138 instances across 12 Python repositories and found LLM-generated context files lowered task success by ~3% versus providing no context at all, while raising inference cost by 20%+. Human-written files improved success by ~4%. The takeaway: hand-curate, and keep it short.

How does Codersera use these files internally?

For full transparency: Codersera's own repos run CLAUDE.md at the root (about 600 lines, structured by section with explicit IMPORTANT markers), a personal ~/.claude/CLAUDE.md with cross-project preferences, and an AGENTS.md in some open-source repos for portability. We do not currently run Cursor MDC rules because we are not Cursor-heavy. We use SKILL.md extensively for publish-to-Ghost, refresh-old-post, and indexer-ping workflows — these are exactly the task-scoped capabilities that fit SKILL.md's shape.

The pragmatic takeaway: pick the format that matches the agents you actually use, keep it under 200 lines per file, and write commands not observations.

FAQ

Do I need both AGENTS.md and CLAUDE.md in the same repo?

If your team uses Claude Code and any other agent (Cursor, Copilot, Codex), yes. AGENTS.md covers everyone else; CLAUDE.md unlocks Claude's three-layer memory model. Keep CLAUDE.md as the canonical, longer file and have AGENTS.md be a shorter pointer that ends with "For Claude Code users: see CLAUDE.md for additional rules."

Is .cursorrules dead?

Not dead, deprecated. Cursor still reads the single-file .cursorrules at the repo root, but it does not support globs, frontmatter, or per-mode activation. New projects should use .cursor/rules/*.mdc. Existing projects can migrate at their leisure — there is no breaking change yet.

Will AGENTS.md replace CLAUDE.md and Cursor rules?

Probably not. AGENTS.md is intentionally minimal so every tool can read it. CLAUDE.md and Cursor MDC carry features (multi-layer memory, frontmatter activation) that the AGENTS.md spec deliberately leaves out. The likely future is layered: AGENTS.md as the universal base, with tool-specific files for tool-specific features.

Where does AGENTS.md actually live in a monorepo?

One at the root for repo-wide defaults, then additional AGENTS.md files inside any package or service that has its own conventions. When an agent edits a file, it walks up the directory tree and uses the nearest AGENTS.md. There is no merging — the closest file wins. OpenAI's main monorepo runs 88 AGENTS.md files this way.

Does GitHub Copilot read AGENTS.md?

Yes, as of late 2025. Copilot reads .github/copilot-instructions.md first (its native format), and then AGENTS.md if present. If you only ship AGENTS.md, Copilot still works.

What goes in CLAUDE.md vs SKILL.md?

CLAUDE.md is standing context — things true for every interaction in the project (code style, build commands, do-not-touch list). SKILL.md is a task capability — something the agent should know how to do but only when asked (publish-to-blog, run-migrations, refresh-old-post). If you find yourself writing "when the user asks to X, do Y" in CLAUDE.md, that paragraph belongs in a SKILL.md instead.

How long should an AGENTS.md or CLAUDE.md be?

Anthropic recommends roughly 200 lines per CLAUDE.md file, with subagents or nested files handling the rest. AGENTS.md has no formal recommendation, but the same rule of thumb applies — past 300 lines, agent recall degrades and you are better off splitting the file. Long steering files are a known anti-pattern; structure beats volume.

Are these files secrets-safe?

Yes — none of the five formats are meant to contain secrets. They are committed to git (except CLAUDE.local.md, which is gitignored) and read by external services. Keep them to conventions, not credentials. Use .env and a secret manager for anything sensitive.

Last reviewed: May 2026.