AGENTS.md vs CLAUDE.md vs Cursor rules: keeping them in sync
Each tool reads its own file: Claude Code reads CLAUDE.md, many other agents (including Codex) read AGENTS.md, Cursor reads rules under .cursor/rules, Copilot reads .github/copilot-instructions.md and Gemini CLI reads GEMINI.md. Keep the real content in one place and make every other file point at it or be generated from it, because hand-maintained copies drift.
Why copies drift
Someone fixes a rule in CLAUDE.md and forgets .cursorrules. Two months later one agent runs the tests before committing and the other does not. Nothing fails; the agents just behave differently on the same repository.
Syncing does not make a bad rule set good: copies of a rotten file are still rotten. Remove contradictions and stale rules first, then sync.
Options, cheapest first
- One real file, others import or link it. Write the shared content in
AGENTS.md; makeCLAUDE.mda one-line file that imports it (Claude Code supports@imports) or a symlink, where your platform allows. - Keep tool-specific parts small and separate (Cursor rule scoping, Claude-only hooks) and say so at the top of each file.
- Generate the native files from one source and check the result. A reviewer in CI catches the drift a human forgets.
A worked example
Skillhawk's compile writes the native file each agent expects from one skill and checks size, frontmatter and lost content. This is real output from the landing page for the release-notes skill (Copilot's code review reads a limited number of characters, which is why that check fails):
$ skillhawk compile release-notes --to all
copilot: FAIL size (4301/4000 chars read by code review)
gemini: GEMINI.md ok size (4385/20000 bytes)
The Skillhawk command that helps
What Skillhawk does here, and what it does not:
npx skillhawk compile <skill-dir> --to claude,codex,cursor,copilot,gemini
npx skillhawk review <dir> # contradictions and duplicate rules inside a file
compile works from a skill folder, not from an existing AGENTS.md. Detecting drift between your instruction files across repositories is not a feature yet.
Questions
Should I use AGENTS.md or CLAUDE.md?
Use both if you use both kinds of agents: put the shared content in AGENTS.md and have CLAUDE.md import or link it, so there is one place to edit.
Can Skillhawk sync my CLAUDE.md and .cursorrules?
Not directly. It compiles a skill to native files for Claude Code, Codex, Cursor, Copilot and Gemini and checks each one. It does not yet diff your existing instruction files against each other.
Sources
- Unblocked: Keeping CLAUDE.md, AGENTS.md and .cursorrules in sync
"Multi-file rules drift is the divergence that builds up when several AI coding tools each read their own instruction file." - DEV Community: Keep AGENTS.md and CLAUDE.md in sync, 5 user-side fixes
- DEV Community: One memory to rule them all, taming AI CLI instruction sprawl