AGENTS.md, Explained: One File for Claude, Cursor, Copilot and Windsurf

If you use more than one AI coding agent on the same project, you've probably noticed the file sprawl: an AGENTS.md, a CLAUDE.md, a .cursor/rules/ directory, a .github/copilot-instructions.md, maybe a .windsurf/rules/. They all say roughly the same thing — how to build the project, what conventions to follow — and they all drift apart the moment you change one and forget the others.

This post explains what AGENTS.md is, why it exists, and how to keep the whole set in sync without hand-copying between formats.

What AGENTS.md actually is

AGENTS.md is a plain-Markdown file at your repository root that tells an AI coding agent what it needs to know about your project. There are no required fields and no special schema — just Markdown headings you'd recognise from any README:

# Project overview
A Next.js + TypeScript application.

## Setup / install
npm install

## Build, test, and lint
Build: npm run build
Test: npm test
Lint: npm run lint

## Code style and conventions
- TypeScript strict mode — avoid `any` without good reason.
- Prefer server components; add "use client" only where needed.

What makes it more than a convention is adoption. In December 2025, AGENTS.md was donated to the Linux Foundation's Agentic AI Foundation as an open standard, and it's now read natively by Claude Code, Codex, Cursor, Copilot, Gemini CLI, Windsurf, Zed, Aider and roughly thirty other agents. For most tools, a single good AGENTS.md is all you need.

Because AGENTS.md has no required fields, the fastest way to write a good one is to start from a stack-appropriate skeleton — overview, setup, build/test/lint, conventions — and fill in your real commands. That's what the stack presets in the tool below do.

Why you still end up with five files

If everything read AGENTS.md, this would be a non-problem. Two things keep the sprawl alive:

1. A few agents have their own established file. Claude Code looks for CLAUDE.md; Cursor has its .cursor/rules/ directory; older setups still carry a .cursorrules or .windsurfrules.
2. Cursor does something the others don't: per-file scoping. A Cursor rule can be limited to specific globs, which is genuinely useful and has no equivalent in a flat file.

So teams copy the same content into each file, and then the copies rot. A build command changes in AGENTS.md and nobody updates CLAUDE.md. A new convention lands in the Cursor rules and never makes it to Copilot. The files that were meant to keep your agents consistent quietly make them inconsistent.

The fix for CLAUDE.md: bridge, don't duplicate

The most common mistake is pasting your whole AGENTS.md into CLAUDE.md. Don't. Claude Code supports importing another file with an @-reference on the first line, so the recommended CLAUDE.md is a one-line bridge plus only what's genuinely Claude-specific:

@AGENTS.md

## Claude-specific overrides
- Prefer running the test suite with the focused `-t` flag during iteration.

Now the shared instructions live in exactly one place. CLAUDE.md inherits them through the @AGENTS.md import and adds nothing it doesn't need to.

Converting Cursor rules to AGENTS.md (and the glob caveat)

This is the conversion people search for most — "cursor rules to agents.md" — and it's the one with a real subtlety. A Cursor rule is an .mdc file with YAML frontmatter:

---
description: "Testing conventions"
globs: **/*.test.ts, **/*.spec.ts
alwaysApply: false
---
Use Vitest. Co-locate tests with the code they cover.

Converting the body to AGENTS.md is trivial — it's already Markdown. The catch is the globs line. That rule only applies to test files, but AGENTS.md is flat: it applies to the whole project and has no way to express "only for **/*.test.ts".

When a converter flattens a scoped Cursor rule, the scoping is lost. The honest thing to do is record the original glob verbatim — not drop it silently. A rule you think is still scoped, but isn't, is worse than one you know is global.

A good conversion therefore keeps the information visible. Instead of throwing the glob away, it appends the scoped rule under a labelled section and notes where it came from:

## Scoped rules (originally Cursor-only)

### testing-conventions — Testing conventions
> Originally scoped to: **/*.test.ts, **/*.spec.ts

Use Vitest. Co-locate tests with the code they cover.

You keep the content, you can see exactly what was scoped, and you decide what to do about it — rather than a converter quietly pretending the scope survived.

.cursorrules and .windsurfrules are deprecated — read them, don't write them

If you're still carrying a single-file .cursorrules or .windsurfrules, those formats are deprecated. Cursor moved to a .cursor/rules/ directory of .mdc files; Windsurf moved to .windsurf/rules/. The right migration is one-way: read the old single file to recover its content, then emit the current directory-based format. There's no reason to generate a new .cursorrules in 2026.

Doing it without hand-copying

All of the above is mechanical, which means you shouldn't be doing it by hand. Skojio's AGENTS.md Generator & Converter treats AGENTS.md as the single source of truth and derives the rest from it:

• Stack presets — Next.js + TypeScript, Python, Go, Rust, Node.js, or Generic — seed a sensible starting AGENTS.md so you're editing, not staring at a blank file.
• Live format tabs show the CLAUDE.md bridge, Cursor .mdc rules (with real frontmatter and multi-block scoping), Copilot and Windsurf equivalents as you type.
• Import an existing file in any of the formats — including deprecated .cursorrules and .windsurfrules — and convert to the others.
• The glob caveat is surfaced, not hidden: convert a scoped Cursor rule to a flat format and you get the verbatim record shown above plus a plain-language warning.
• Copy any file, or download all five at once as a .zip laid out at the correct paths for a drop-in.

It runs entirely in your browser — nothing you paste or upload is sent anywhere, which matters when the file you're editing describes your private repository. If you work with JSON alongside your agent config, the same in-browser, privacy-first approach powers Skojio's JSON Formatter & Validator and JSON to TypeScript Converter.

• AGENTS.md is an open standard (Linux Foundation, Dec 2025) read natively by ~30 AI coding agents — for most tools, one good AGENTS.md is enough.
• The sprawl persists because a few agents keep their own file (CLAUDE.md, Cursor rules) and Cursor adds per-file glob scoping the flat formats can't express.
• Write CLAUDE.md as a one-line @AGENTS.md bridge plus overrides — never a duplicate that drifts.
• Converting scoped Cursor rules to a flat format loses the scoping; a good converter records the original glob verbatim instead of dropping it silently.
• .cursorrules and .windsurfrules are deprecated — read them to migrate, but emit the current .cursor/rules/ and .windsurf/rules/ directory formats.