skillhawk

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

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

Skillhawk is a tool in this space, so weigh our framing accordingly. Last updated 2026-11-17.

Related

Try skillhawk review