Can Claude Code and Cursor share one instruction file?

Yes, AGENTS.md. Cursor reads it in the project root and subdirectories, and Claude Code reads it as project instructions when there's no CLAUDE.md in the working directory or above it.

What if my repo already has a CLAUDE.md?

By default Claude Code then reads CLAUDE.md instead of AGENTS.md. Put `@AGENTS.md` at the top of CLAUDE.md to import it, or change the Project instructions setting.

Where do Cursor project rules live?

In `.cursor/rules` as `.mdc` files with frontmatter. Cursor ignores a plain `.md` file in that folder.

Where do Claude Code rules live?

In `.claude/rules/` as markdown files, optionally scoped with a `paths` field in frontmatter. Personal rules go in `~/.claude/rules/`.

What should I share and what should I split?

Share commands, conventions, the definition of done and hard stops in AGENTS.md. Keep file-scoped rules in each tool's own rules folder, since the formats differ.

Does either tool enforce these instructions?

No. Both treat them as context for the model. For a hard block in Claude Code, its docs point to hooks or permission settings.

One agent setup for Claude Code and Cursor: what to share, what to split

You can keep **one shared instruction source** and **one shared skills tree** for Claude Code and Cursor, then leave each tool's rules and MCP config alone. Cursor reads `AGENTS.md` (root + nested) and `.cursor/rules` as `.mdc` files. Claude Code's primary file is `CLAUDE.md` (or `.claude/CLAUDE.md`); from v2.1.277 it also reads `AGENTS.md` when no `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` exists at or above the working directory. Neither tool's docs say it loads the other's rules folder, so treat rules as split. Skills share cleanly: both load `.claude/skills/` (Cursor also loads `~/.claude/skills/` for compatibility).

Who this is for

Your team switches between Cursor and Claude Code on the same repo and you want one source of truth for conventions without inventing a second copy of every rule.

Share vs split

Layer	Share	Split
Project instructions	`AGENTS.md` (root + nested) as the common file	Claude-only extras in `CLAUDE.md`; Cursor-only always-on rules in `.cursor/rules/*.mdc`
Path-scoped rules	—	`.claude/rules/.md` (optional `paths`) vs `.cursor/rules/.mdc` (`globs` / `alwaysApply`)
Skills	`.claude/skills/<name>/SKILL.md` (both tools load this path)	Cursor-only skills can also live in `.cursor/skills/` or `.agents/skills/`
MCP config	—	`.cursor/mcp.json` / `~/.cursor/mcp.json` for Cursor; Claude Code's own MCP config. Formats differ—don't assume one file serves both

For the instruction-file contrast in more detail, see AGENTS.md vs CLAUDE.md vs Cursor rules. For Connect auth differences between the two clients, see Claude vs Cursor MCP auth.

One instruction file that both can read

Cursor. `AGENTS.md` is a plain-markdown alternative to `.cursor/rules`. Nested files apply in that directory and its children, with more specific instructions taking precedence. Cursor also reads `CLAUDE.md` the same way it reads `AGENTS.md` (always applied).

Claude Code. By default (`claude-md-or-agents-md`), it reads `AGENTS.md` only when there is no `CLAUDE.md` / `.claude/CLAUDE.md` / `CLAUDE.local.md` on the path upward. If `CLAUDE.md` already exists, put `@AGENTS.md` at the top to import the shared file, or set Project instructions to `claude-md-and-agents-md`. Direct `AGENTS.md` reading needs v2.1.277+; in sessions that can't load it, the `@AGENTS.md` import still works.

A practical layout:

text

repo/
  AGENTS.md                 # shared: build/test, conventions, hard stops
  CLAUDE.md                 # optional: @AGENTS.md + Claude-only notes
  .claude/
    rules/                  # Claude path-scoped rules
    skills/my-skill/SKILL.md
  .cursor/
    rules/                  # Cursor .mdc rules only

On Windows, Claude Code docs prefer the `@AGENTS.md` import over a `CLAUDE.md` → `AGENTS.md` symlink.

Skills: one tree both discover

Claude Code loads project skills from `.claude/skills/<skill>/SKILL.md` (personal: `~/.claude/skills/`). Cursor's primary project locations are `.agents/skills/` and `.cursor/skills/`; for compatibility it also loads `.claude/skills/`, `.codex/skills/`, `~/.claude/skills/`, and `~/.codex/skills/`. Shared skills under `.claude/skills/` match both documented load paths. Keep Cursor-only experiments in `.cursor/skills/` if you don't want them in Claude sessions.

What stays tool-specific

Rules format. Cursor project rules must be `.mdc` with frontmatter; a plain `.md` in `.cursor/rules` is ignored. Claude Code rules are markdown under `.claude/rules/`, optionally with a `paths` field.
MCP config files. Cursor documents `.cursor/mcp.json` and `~/.cursor/mcp.json`. Do not treat those as Claude Code's config, or the reverse.
Hooks and permissions. Claude Code PreToolUse hooks and permission settings are Claude-specific hard controls; Cursor has its own hooks and approval modes. Don't claim one enforces the other's files.

Neither product treats instruction files as enforcement. Claude Code docs say CLAUDE.md is context, not a hard block—use hooks or permissions when something must never run. Cursor rules likewise guide Agent; they are not a filesystem guard.

Pitfalls

Duplicating the same prose in AGENTS.md and CLAUDE.md. Drift is the bug. Import or symlink (or rely on Cursor reading both) instead of copy-paste.
Expecting Claude Code to read AGENTS.md while a CLAUDE.md sits on the path. Default setting skips AGENTS.md in that case.
Putting Cursor rules in a nested `.cursor/rules` under a package. Cursor discovers project rules from the workspace `.cursor/rules`; use nested `AGENTS.md` or root rules with globs for package scope.
Sharing one MCP JSON across tools. Not documented as a shared format—configure each client.
Assuming every Claude Code session loads AGENTS.md. Version, plugin disable, or `claude-md` / `managed-only` settings can leave it out; keep the `@AGENTS.md` import as a fallback.

How to check it

In Cursor, open Agent on a file under a nested folder that has its own `AGENTS.md` and confirm those instructions apply.
In Claude Code, run `/context` or `/memory` and confirm which of `CLAUDE.md`, `AGENTS.md`, and rules files loaded.
Add a skill only under `.claude/skills/demo/SKILL.md` and confirm both tools can invoke or discover it.
Confirm a `.md` file in `.cursor/rules` does not show as a project rule (needs `.mdc`).

Where ShipKits fits

The Operator Pack ($47) is markdown seats + skills + install.sh — not a hosted app, not a chatbot. Seven named seats. Three skills. Ops playbook + token-cost playbook. Done means a file, PR, or URL. The zip includes snippets for AGENTS.md + CLAUDE.md, and install.sh copies skills into `.cursor/skills` and `.claude/skills`. Soft path: /free. Cheat Sheet for the skim checklist mindset.

Soft next step

Commit one `AGENTS.md`, point Claude at it with `@AGENTS.md` if you already have `CLAUDE.md`, and put shared skills under `.claude/skills/`. Soft ladder: /free, then the Operator Pack ($47). Related: AGENTS.md vs CLAUDE.md vs Cursor rules, AGENTS.md for Cursor, Claude Code, and Codex, Claude vs Cursor MCP auth.