SKILL.md vs CLAUDE.md vs .cursorrules vs AGENTS.md

Key takeaways

All five encode the same thing — conventions, constraints, context — but they differ on scope, activation, and portability.
AGENTS.md is the only cross-tool one; the rest are native to a single tool.
CLAUDE.md = facts (always on); SKILL.md = procedures(on demand). They’re complementary, not competing.
Running 2+ tools means maintaining 2+ files. Sync them by converting or by compiling from one canonical source.

The five formats at a glance

Format	Tool	Location	Activation	Portable?
`SKILL.md`	Claude Code (+ open standard)	`.claude/skills/…`	On demand (named / auto)	Open standard
`CLAUDE.md`	Claude Code	Repo root / nested	Always on	Claude only
`.cursorrules` / `.mdc`	Cursor	Root / `.cursor/rules/`	4 modes (globs, etc.)	Cursor only
`AGENTS.md`	24+ tools	Repo root / nested	Always on (nearest wins)	Yes
`copilot-instructions.md`	GitHub Copilot	`.github/`	Repo-wide + path-specific	Copilot only

Format by format

SKILL.md (Claude Code)

A folder with a SKILL.md that loads on demand — best for procedureslike “run a security review” or “generate a migration.” Loads only when relevant, so it costs almost nothing until used. Deep dive: the complete guide to Claude Code skills and SKILL.md.

CLAUDE.md (Claude Code)

Always-on project memory — the facts Claude needs every turn: what the project is, the stack, the non-negotiables. Supports @imports, a CLAUDE.local.md for personal overrides, and hierarchical memory up the directory tree. The rule of thumb: facts go here, procedures become skills.

.cursorrules / .cursor/rules (Cursor)

The legacy .cursorrules root file is being phased out in favor of .cursor/rules/*.mdc, which adds frontmatter (description, globs, alwaysApply) and four activation modes. The most expressive scoping of the five. Deep dive: the complete guide to Cursor rules.

AGENTS.md (cross-tool)

Plain Markdown read by Codex, Cursor, Copilot, Gemini, and two dozen-plus other tools — the only portable option. No scoping, no frontmatter, no tool lock-in. The catch: Claude Code doesn’t read it natively. Deep dive: the AGENTS.md standard.

copilot-instructions.md (GitHub Copilot)

Repo-wide instructions at .github/copilot-instructions.md, plus path-specific .instructions.md files with applyTo globs. Tightly integrated with the GitHub workflow. Deep dive: the complete GitHub Copilot instructions guide.

Which format should your rules live in?

You only use one tool:use its native format. Cursor → .cursor/rules. Claude Code → CLAUDE.md + skills. Copilot → copilot-instructions.md.
You want maximum portability: start with AGENTS.md — but add a CLAUDE.md import if you use Claude Code.
You need procedures, not just conventions: reach for Claude Code skills (on-demand) rather than stuffing everything into an always-on file.
You use two or more tools: see the next section — this is where it gets hard.

The multi-tool drift problem

The real cost

The moment you run more than one tool, ~80% of each file is identical and the other 20% is where things break. You fix a rule in .cursorrules after a painful bug; the lesson never reaches CLAUDE.md or copilot-instructions.md; six months later the same bug comes back through a different tool. There’s no npm audit for prompts, and no version history that tells you which file is authoritative.

For the four-format deep comparison and the six ways this drift bites, see the cornerstone: SKILL.md vs .cursorrules vs Windsurf rules vs Copilot instructions.

How to keep them in sync

There are two honest answers:

Convert when something changes. Maintain one file and port the diff to the others. See convert .cursorrules to CLAUDE.md, AGENTS.md & Copilot for the field-by-field mapping. Works, but the porting is manual forever.
Compile from one canonical source.Keep your rules and skills in a single library and generate each tool’s file automatically. That’s what Skillwright does — author once, deploy to Cursor, Claude Code, Windsurf, and Copilot, with drift surfaced instead of discovered.

Either way, the full playbook for a multi-tool setup is in how to manage AI coding rules across tools. Or skip straight to ready-made rule and skill templates.

Frequently asked questions

Which AI rules file format should I use?

Use the native format of whatever tool you're in: SKILL.md/CLAUDE.md for Claude Code, .cursor/rules for Cursor, copilot-instructions.md for Copilot, .windsurf/rules for Windsurf. If you want one portable file across tools, use AGENTS.md — but note Claude Code doesn't read it natively.

Can one file replace all my AI rule files?

Partly. AGENTS.md is read by most tools and can be a single source of truth for plain conventions. But Cursor's .mdc globs and Claude Code's memory model add capabilities AGENTS.md doesn't have, so a single file usually can't express everything every tool supports.

What's the difference between SKILL.md and CLAUDE.md?

CLAUDE.md is always-on project memory (facts loaded every turn). SKILL.md is an on-demand procedure that loads only when relevant. They're complementary: facts in CLAUDE.md, repeatable procedures in skills.

Do these rule files work across different AI coding tools?

No — each is tool-specific except AGENTS.md, which is a cross-tool open standard. That's why teams running multiple tools end up maintaining several files with overlapping content, and why keeping them in sync becomes a real problem.

How do I keep multiple rule files in sync?

Either convert from one format to the others whenever something changes, or keep one canonical source and compile to each tool's format automatically. Manual copy-paste across files is what causes drift, where a fix in one file never reaches the others.