Cursor rules vs skills vs AGENTS.md vs CLAUDE.md
When to use Cursor rules, Cursor skills, AGENTS.md, or CLAUDE.md: how each loads, and a setup that works in both Cursor and Claude Code without duplicates.
A team uses Cursor and Claude Code side by side. The repository has .cursor/rules/ with twelve .mdc files, a CLAUDE.md, an AGENTS.md someone added for Codex, and a .claude/skills/ folder. Half the instructions exist in three places, and they've started to disagree.
Each format exists for a reason, and the overlap is smaller than it looks. This guide explains how each one loads, when to use which, and a layout that serves both tools without copies, from Cursor's rules and skills documentation and Anthropic's memory and skills documentation, checked on 16 November 2026.
The short answer
| Cursor project rules | Cursor skills | AGENTS.md | CLAUDE.md | |
|---|---|---|---|---|
| Location | .cursor/rules/*.mdc | .cursor/skills/, .agents/skills/, .claude/skills/ | Repo root, and subdirectories | Repo root, and subdirectories |
| Read by | Cursor | Cursor, and Claude Code from .claude/skills/ | Cursor, Codex, Claude Code, and others | Claude Code |
| Loads | Always, by file pattern, by description, or when @-mentioned | When relevant, or via /skill-name | Every session | Every session |
| Format | Frontmatter plus markdown, .mdc only | SKILL.md folder with optional scripts and references | Plain markdown | Plain markdown, with @ imports |
| Best for | Cursor-specific scoping | Procedures and workflows | Shared instructions for every agent | Claude Code specifics |
Cursor project rules
Project rules live in .cursor/rules/ and must use the .mdc extension; a plain .md file there is ignored. Three frontmatter fields, alwaysApply, description, and globs, decide when a rule loads:
| Rule type | Loads |
|---|---|
| Always Apply | In every chat session |
| Apply Intelligently | When the agent decides it's relevant from the description |
| Apply to Specific Files | When a file matching the pattern is in context |
| Apply Manually | When you @-mention it, like @my-rule |
Cursor also has User Rules, global to your environment, and Team Rules managed from the dashboard on Team and Enterprise plans.
Use project rules when you need Cursor's scoping, for example frontend conventions that should only load for files under src/components/.
Cursor skills
Cursor supports Agent Skills, which its documentation describes as an open standard. A skill is a folder with a SKILL.md and optional scripts/, references/, and assets/. It loads when the agent decides it's relevant, or only when you type /skill-name if you set disable-model-invocation: true. Scoping uses a paths field.
Cursor reads skills from .cursor/skills/ and .agents/skills/ in the project and ~/.cursor/skills/ and ~/.agents/skills/ for you. For compatibility, it also loads skills from Claude Code and Codex folders: .claude/skills/, .codex/skills/, ~/.claude/skills/, and ~/.codex/skills/.
Cursor is moving description-based rules toward skills. Its /migrate-to-skills command converts "Apply Intelligently" rules, meaning alwaysApply: false with no globs, and slash commands into skills.
AGENTS.md
AGENTS.md is plain markdown with no metadata. Cursor's documentation calls it a simple alternative to .cursor/rules, and supports it in the project root and in subdirectories. Its advantage is reach: Codex reads it natively, Claude Code reads it since v2.1.277 when there's no CLAUDE.md, and many other agents support it. For the details, see AGENTS.md vs CLAUDE.md.
CLAUDE.md
CLAUDE.md is Claude Code's own instruction file, with extras such as user-level and organization-level files, @ imports, and path-scoped rules in .claude/rules/. Cursor's rules documentation doesn't list it. If both tools need the same instructions, keep them in AGENTS.md and make CLAUDE.md import it. For what to write, see CLAUDE.md examples.
A layout that works in both tools
AGENTS.md # shared instructions: commands, gotchas, boundaries
CLAUDE.md # "@AGENTS.md" plus anything Claude Code specific
.cursor/rules/
frontend.mdc # Cursor-only scoping, globs: src/components/**
.claude/rules/
frontend.md # Claude Code equivalent, paths: src/components/**
.claude/skills/
release/SKILL.md # one skill, loaded by both Claude Code and Cursor
new-migration/SKILL.md
The rules are written once per tool, because their scoping formats differ: globs in Cursor, paths in Claude Code. Everything else lives once:
- Instructions in AGENTS.md, read by both.
- Skills in
.claude/skills/, which Claude Code reads natively and Cursor reads for compatibility. Stick to fields both understand, such asname,description, anddisable-model-invocation.
Common mistakes
| Mistake | Result | Fix |
|---|---|---|
.md files in .cursor/rules/ | Cursor ignores them | Rename to .mdc, or move to AGENTS.md |
| The same instructions in AGENTS.md, CLAUDE.md, and rules | They drift apart | One source in AGENTS.md; CLAUDE.md imports it |
| A CLAUDE.md that only says "read AGENTS.md" | Claude Code may not open it | Use @AGENTS.md, an import |
| Every rule set to Always Apply | Context fills with irrelevant rules | Scope by files or description, or make it a skill |
| Procedures written as rules | Loaded even when not needed | Move them to skills |
What none of these formats track
Rules, skills, AGENTS.md, and CLAUDE.md all hold text that someone has to keep current. None of them has an owner per line, a status, or a record of what replaced what. That's fine for conventions. It breaks down for decisions that change, such as which API version is being retired or which customers get an exception.
Where Lockstep fits
Lockstep keeps those decisions in one shared record instead of in per-tool files. Decisions are captured from PRDs, Slack, and pull requests and become binding when their owner approves them. Claude Code is briefed on the ones that apply at the start of each session; Cursor can query the same record through Lockstep's MCP server, without the automatic briefing. When a decision changes, the old version is marked replaced.
Session briefings work with Claude Code today. See how it works.
Sources checked 16 November 2026
- https://cursor.com/docs/context/rules
- https://cursor.com/docs/context/skills
- https://code.claude.com/docs/en/memory
- https://code.claude.com/docs/en/skills
Related reading
For moving between the two tools, see how to share memory between Cursor and Claude Code. For Codex as well, see Claude Code vs Cursor vs Codex. For skills in depth, see Claude Code skills: 6 examples. Definitions: AGENTS.md, CLAUDE.md. For the format shared across Claude Code, Codex, and Cursor, see the Agent Skills open standard. For GitHub Copilot's equivalents, see AGENTS.md vs copilot-instructions.md. For Cursor against Antigravity and Claude Code overall, see Cursor vs Antigravity vs Claude Code.
Frequently asked questions
- What is the difference between Cursor rules and skills?
- Rules are context included at the start of the model context, always or when a file pattern or description matches. Skills are packages of instructions, scripts, and references the agent loads when relevant or when you type /skill-name. Cursor's /migrate-to-skills command converts description-based rules and slash commands into skills.
- Should I use Cursor rules or AGENTS.md?
- AGENTS.md for plain instructions you want every coding agent to read, since Codex, Claude Code, and others support it. Cursor project rules when you need Cursor-specific scoping, such as a rule that applies only to files matching a pattern.
- Does Cursor read CLAUDE.md?
- Cursor's rules documentation covers .cursor/rules, User Rules, Team Rules, and AGENTS.md, and doesn't list CLAUDE.md. For shared instructions, put them in AGENTS.md and have CLAUDE.md import it with @AGENTS.md.
- Can the same skill work in Cursor and Claude Code?
- Yes. Cursor loads skills from .claude/skills/ and ~/.claude/skills/ for compatibility, as well as .cursor/skills/ and .agents/skills/. A SKILL.md in .claude/skills/ works in both, as long as it only uses frontmatter fields both tools understand.
- Why must Cursor rules use .mdc?
- Cursor's documentation says project rules must use the .mdc extension. A plain .md file in .cursor/rules is ignored by the rules system. If you prefer plain markdown, use AGENTS.md.
Keep reading