Short answer: keep your instructions in AGENTS.md. 12 of 17 agents we track read it natively. Add a CLAUDE.md containing @AGENTS.md for Claude Code, set context.fileName for Gemini CLI, add read: [AGENTS.md] for Aider, and delete legacy .rules/.cursorrules files that Zed reads first.
AGENTS.md vs CLAUDE.md
| AGENTS.md | CLAUDE.md | |
|---|---|---|
| Read by | Codex CLI, Cursor, GitHub Copilot, Devin Desktop (ex-Windsurf), Cline, Roo Code, Kilo Code, OpenCode, Amp, Kiro, Jules, Factory Droid; with caveats: Claude Code, Antigravity / Gemini CLI, Aider, Zed | Claude Code; also Devin Local, OpenCode and Amp (as fallbacks), the Copilot cloud agent, Zed (low priority) |
| Imports | No standard import syntax | @path/to/file imports, up to four hops deep |
| Personal overrides | AGENTS.override.md (Codex), AGENTS.local.md (Devin Local) | CLAUDE.local.md |
| Scoped rules | Nested AGENTS.md in subfolders | Nested CLAUDE.md, .claude/rules/*.md with paths: |
Setup in one go
Run from the repository root (macOS/Linux shell). Skip the lines for agents you don't use.
# 1. One source of truth
touch AGENTS.md
# 2. Claude Code: thin wrapper (works on every OS)
printf '@AGENTS.md\n\n## Claude Code only\n' > CLAUDE.md
# ...or a symlink (macOS/Linux; Windows needs core.symlinks=true)
# ln -s AGENTS.md CLAUDE.md
# 3. Gemini CLI: read AGENTS.md as well as GEMINI.md
mkdir -p .gemini && printf '{\n "context": { "fileName": ["AGENTS.md", "GEMINI.md"] }\n}\n' > .gemini/settings.json
# 4. Aider: load it on every run
printf 'read: [AGENTS.md]\n' >> .aider.conf.yml
# 5. Zed: remove legacy files that outrank AGENTS.md
git rm --cached -q .rules .cursorrules .windsurfrules .clinerules 2>/dev/null || true
# 6. Shared skills: one folder, Claude Code via symlink
mkdir -p .agents/skills .claude && ln -sfn ../.agents/skills .claude/skills
Symlink or import?
- Import (
@AGENTS.mdin CLAUDE.md): works on every OS and lets you add Claude-only notes below. Recommended for teams. - Symlink (
ln -s AGENTS.md CLAUDE.md): zero duplication, but Git on Windows checks symlinks out as small text files unlesscore.symlinks=trueand Developer Mode are on. Claude Code's docs show both options. - Copying the file is the option to avoid: the copies drift.
Per-agent caveats
| Agent | Reads AGENTS.md | What to do |
|---|---|---|
| Claude Code | ◐ Partial | Add a CLAUDE.md whose first line is @AGENTS.md (or ln -s AGENTS.md CLAUDE.md). With no CLAUDE.md at all, v2.1.277+ reads AGENTS.md directly. |
| Codex CLI | ✓ Yes | Native: nothing to do. Use AGENTS.override.md for temporary local overrides. |
| Cursor | ✓ Yes | Native (root and nested). Add .cursor/rules/*.mdc only for glob-scoped rules. |
| GitHub Copilot | ✓ Yes | Native in VS Code (chat.useAgentsMdFile) and the cloud agent. Keep .github/copilot-instructions.md only for Copilot-specific notes. |
| Antigravity / Gemini CLI | ◐ Partial | Antigravity: native. Gemini CLI: set context.fileName to ["AGENTS.md", "GEMINI.md"] in .gemini/settings.json (or symlink GEMINI.md). |
| Devin Desktop (ex-Windsurf) Changed | ✓ Yes | Native: root AGENTS.md is an always-on rule; subfolder files are scoped. |
| Cline | ✓ Yes | Native: AGENTS.md is detected automatically. |
| Roo Code Discontinued | ✓ Yes | Native (product discontinued). |
| Kilo Code | ✓ Yes | Native: loaded automatically from the project root and subfolders. |
| Aider | ◐ Partial | Add read: [AGENTS.md] to .aider.conf.yml (or run aider --read AGENTS.md). |
| OpenCode | ✓ Yes | Native. If CLAUDE.md also exists, OpenCode uses only AGENTS.md. |
| Zed | ◐ Partial | Native, but delete .rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md and AGENT.md, which win over AGENTS.md. |
| Amp | ✓ Yes | Native (cwd, parents and subtrees). |
| Kiro | ✓ Yes | Native: always included as steering. |
| Jules | ✓ Yes | Native: repository-root AGENTS.md only. |
| Factory Droid | ✓ Yes | Native (also in .factory/ and .agents/). |
| Continue Discontinued | ? Not documented | Not documented: copy the content into .continue/rules/. |
Size limits that bite
- Codex stops reading instruction files at 32 KiB (
project_doc_max_bytes). - Devin Desktop caps workspace rule files at 12,000 characters and global rules at 6,000.
- Claude Code recommends keeping each CLAUDE.md under about 200 lines.
- Zed and Antigravity load only some files: Zed takes the first matching project file, Antigravity only top-level
.agents/rules/*.md.
Check your file with the AGENTS.md linter.
Sharing skills across agents
.agents/skills/<name>/SKILL.md is read by Claude Code, Codex CLI, Cursor, GitHub Copilot, Antigravity / Gemini CLI, Devin Desktop (ex-Windsurf), Kilo Code, OpenCode, Zed, Amp, Factory Droid. Claude Code reads .claude/skills, so symlink it (step 6 above). Try it with our free Agent Skills.
MCP servers can't be shared yet
Every agent keeps MCP servers in its own file (see the MCP location table). Most accept the same mcpServers JSON, so you can copy the server blocks between .mcp.json, .cursor/mcp.json and others; VS Code (servers), Codex (TOML) and OpenCode/Kilo (mcp) need reshaping.
FAQ
AGENTS.md vs CLAUDE.md: what is the difference?
Both are plain Markdown instructions loaded at the start of a session. AGENTS.md is the cross-tool convention read by Codex, Cursor, Copilot, Antigravity, Devin Desktop, Cline, Kilo Code, OpenCode, Amp, Kiro, Jules and Factory. CLAUDE.md is Claude Code's own file; Claude Code also supports @imports, .claude/rules and CLAUDE.local.md.
Should I symlink CLAUDE.md to AGENTS.md or use an import?
Use a CLAUDE.md that contains @AGENTS.md if anyone on the team uses Windows or you want Claude-specific notes; use a symlink (ln -s AGENTS.md CLAUDE.md) for the simplest single-file setup on macOS and Linux.
Can I have AGENTS.md and CLAUDE.md in the same repo?
Yes, but note that Claude Code then reads only CLAUDE.md by default (unless it imports @AGENTS.md or you enable claude-md-and-agents-md), and OpenCode reads only AGENTS.md. Keep CLAUDE.md as a thin wrapper around AGENTS.md so they never drift.
Do nested AGENTS.md files work?
In most agents, yes: Codex (between repo root and launch directory), Cursor, Copilot cloud agent, Devin Desktop, Kilo Code, Amp and Factory scope subfolder files to that directory. Claude Code uses nested CLAUDE.md files instead.
How do I share skills across agents?
Put skills in .agents/skills/<name>/SKILL.md, which Codex, Cursor, Copilot, Antigravity, Devin Desktop, Kilo Code, OpenCode, Amp, Factory and Zed read. Claude Code needs .claude/skills, so symlink .claude/skills to ../.agents/skills.