Cursor rules vs AGENTS.md is a choice about scope and activation. Cursor’s .mdc rules can attach by file pattern, relevance or explicit selection. AGENTS.md carries plain Markdown instructions whose loading depends on the client. Preserve those semantics when mapping to CLAUDE.md, scoped rules or reusable skills.
This guide expands the instruction-file step in our Cursor-to-Claude Code migration assessment. It gives you a concrete mapping example and tests for the destination repository.
Last verified: October 27, 2026. Client behavior below follows the linked vendor documentation. The mapping is an illustrative proposal, not an executed conversion benchmark.
Disclosure: ASCENDING Inc develops Jarvis Crosswalk for AI tool migration assessments. Confirm current collection and delivery scope before relying on it.
Cursor rules vs AGENTS.md: choose by scope
Start by inventorying the behavior each instruction creates. Record its source file, activation condition, applicable paths and expected result.
| Instruction type | Example | Likely destination |
|---|---|---|
| Repository-wide convention | Use the existing package manager | Shared repository instructions |
| File-specific guidance | React components use named exports | Scoped rule or appropriately placed directory instructions |
| Reusable procedure | Produce release notes from a change list | Skill with references or templates |
| Tool permission | Require approval before deployment | Host or organization policy, verified separately |
| Local preference | Personal editor shortcuts | User configuration rather than shared repository policy |
This classification prevents a narrow rule from becoming global guidance. It also keeps prose instructions separate from enforceable tool permissions.
Cursor rules vs AGENTS.md vs CLAUDE.md
Cursor’s rules documentation describes project .mdc files in .cursor/rules. Its frontmatter controls always-applied, file-attached, relevance-based and manual behavior.
OpenAI’s AGENTS.md guide documents how Codex assembles repository instructions, including AGENTS.override.md. Those conventions aren’t a universal promise about every other client.
| Property | Cursor project rules | AGENTS.md | Claude Code instructions |
|---|---|---|---|
| File shape | .mdc with trigger metadata | Plain Markdown | CLAUDE.md, imports and .claude/rules |
| Scope mechanism | Rule metadata and file patterns | Client-specific directory discovery | Directory loading and path-scoped rules |
| Manual task procedure | Possible, but mixed with guidance | Possible, but adds persistent instructions | Prefer a skill for a reusable task |
| Migration risk | Trigger metadata gets lost | Another client loads a different scope | Imports or local files change what loads |
| Acceptance evidence | Rule applies to intended files | Intended file appears in loaded context | Loaded context and path behavior match the proposal |
Cursor rules vs AGENTS.md: verify Claude Code’s current fallback
Claude Code’s memory documentation now documents direct AGENTS.md support beginning with v2.1.277. By default, an applicable CLAUDE.md or CLAUDE.local.md takes precedence over that fallback.
The same documentation lists session restrictions and configuration options. Check your installed version and inspect loaded instructions rather than assuming the presence of AGENTS.md guarantees use.
For teams supporting several clients, choose an explicit policy: shared instructions with documented imports, or independently maintained client files checked for drift. Either approach needs acceptance tests.
Map a scoped Cursor rule without broadening it
Suppose the source rule applies only to React components:
---
globs: src/components/**/*.tsx
alwaysApply: false
---
Use named exports for React components.
Keep each component's styles beside the component.The migration inventory should record both the two instructions and the globs trigger. Pasting only the body into the repository’s root AGENTS.md changes its scope.
For Claude Code, a proposed path-scoped rule could be:
---
paths:
- "src/components/**/*.tsx"
---
Use named exports for React components.
Keep each component's styles beside the component.Place that rule in an appropriate .claude/rules file and verify it using the documented path-scoped rule behavior. The metadata mapping is a candidate equivalent that still needs a real client test.
For a Codex-oriented repository, a directory AGENTS.md may express local guidance when its documented discovery scope matches the intended work. It doesn’t reproduce every arbitrary Cursor glob automatically.
Test both the matching and nonmatching file
Use one component fixture and one unrelated backend fixture. Ask the destination client to make the same small change in each.
The component should follow the named-export convention. The backend task should retain its own conventions without inheriting unrelated component guidance.
Also test a session launched from a subdirectory. A rule that works only from the repository root may fail the team’s ordinary workflow.
Cursor rules vs skills: keep workflows separate
A rule saying “all components use named exports” is persistent guidance. A procedure saying “review a release, inspect its changelog and draft release notes” is a task workflow.
The Agent Skills specification defines packages containing SKILL.md and optional supporting resources. That structure suits a reusable procedure with a template or script.
Keep the procedure in a skill when users need it only for particular tasks. Keep the repository convention in the relevant instruction scope.
Moving a rule into a skill introduces a new acceptance question: will the intended user or agent activate it? Use the shared skill library guide for discovery, invocation and update tests.
Neither a rule nor a skill should be your only control against an unauthorized deployment. Verify host permissions and organization policy separately.
Acceptance tests for repository instruction migration
Use a fresh session for each important case. Record client version, working directory, loaded instruction files and the resulting diff.
| Fixture | Expected behavior | Failure to investigate |
|---|---|---|
| Repository-wide setup question | Correct package manager and test command | Global or personal guidance overrides the project |
| Matching component path | Component convention applies | Trigger or path translation failed |
| Unrelated backend path | Backend convention remains intact | Scoped rule became repository-wide |
| Nested working directory | Applicable parent and local instructions load | Discovery differs from the proposal |
| Existing CLAUDE.md plus AGENTS.md | Behavior matches chosen loading policy | Team assumed both loaded automatically |
| Explicit reusable workflow | Approved skill is selected and resources resolve | Procedure was copied but never activated |
Choose observable outcomes. Asking the model whether it “understands the rule” is weaker evidence than checking a resulting diff and the loaded context.
Keep the original files until those tests pass. Record any manual-only procedure or unsupported trigger as a gap in the migration plan.
Where Jarvis Crosswalk fits
A useful assessment delivers an instruction inventory, proposed destinations, unresolved differences and acceptance fixtures. It should distinguish collected text from verified equivalent behavior.
We build Jarvis Crosswalk at ASCENDING Inc. Confirm its current coverage and outputs through our contact page; don’t assume an available automated scanner or a tested conversion path.
For the wider change, use the coding-agent migration readiness assessment. Before collecting files, shadow AI discovery helps identify the tools, accounts and local workflows the team actually uses.
References
- Cursor rules
- OpenAI: custom instructions with AGENTS.md
- Claude Code: memory, instructions and scoped rules
- Agent Skills specification
Cursor rules and repository instruction migration questions
What is the difference between Cursor rules and AGENTS.md?
Cursor project rules use .mdc files with metadata controlling when guidance applies. AGENTS.md is plain Markdown guidance interpreted by the host agent. Moving text between them requires preserving scope and activation behavior, not just changing the filename.
Does Claude Code read AGENTS.md?
Current documentation says direct support requires Claude Code v2.1.277 or later. By default, it reads AGENTS.md when no applicable CLAUDE.md or CLAUDE.local.md exists in the working directory or above. Some sessions have different availability, so check the documented conditions and inspect the loaded instructions.
Are Cursor rules and skills interchangeable?
Use rules for repository guidance that should apply under a defined scope or trigger. Use skills for reusable task procedures with optional scripts, references and templates. Skill discovery and activation are separate from file-scoped rule attachment.
Can Jarvis Crosswalk automatically convert all our rules?
Don't assume automatic conversion or verified feature parity. Confirm current collection coverage and assessment outputs with ASCENDING. Review proposed mappings and test each important instruction in the destination client before rollout.
