lockstep
5 min readNaman Jain

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 rulesCursor skillsAGENTS.mdCLAUDE.md
Location.cursor/rules/*.mdc.cursor/skills/, .agents/skills/, .claude/skills/Repo root, and subdirectoriesRepo root, and subdirectories
Read byCursorCursor, and Claude Code from .claude/skills/Cursor, Codex, Claude Code, and othersClaude Code
LoadsAlways, by file pattern, by description, or when @-mentionedWhen relevant, or via /skill-nameEvery sessionEvery session
FormatFrontmatter plus markdown, .mdc onlySKILL.md folder with optional scripts and referencesPlain markdownPlain markdown, with @ imports
Best forCursor-specific scopingProcedures and workflowsShared instructions for every agentClaude 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 typeLoads
Always ApplyIn every chat session
Apply IntelligentlyWhen the agent decides it's relevant from the description
Apply to Specific FilesWhen a file matching the pattern is in context
Apply ManuallyWhen 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 as name, description, and disable-model-invocation.

Common mistakes

MistakeResultFix
.md files in .cursor/rules/Cursor ignores themRename to .mdc, or move to AGENTS.md
The same instructions in AGENTS.md, CLAUDE.md, and rulesThey drift apartOne source in AGENTS.md; CLAUDE.md imports it
A CLAUDE.md that only says "read AGENTS.md"Claude Code may not open itUse @AGENTS.md, an import
Every rule set to Always ApplyContext fills with irrelevant rulesScope by files or description, or make it a skill
Procedures written as rulesLoaded even when not neededMove 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

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