migrate-to-cursor

Migrate Claude Code Configurations to Cursor

Discover all Claude Code configuration files in this repository and create Cursor equivalents that reference the originals — no content duplication.

Mapping rules

Source	Cursor equivalent	Strategy
CLAUDE.md (symlink to AGENTS.md/.cursorrules)	—	Already compatible, nothing to do
CLAUDE.md (plain, no @refs)	AGENTS.md	symlink to CLAUDE.md
CLAUDE.md (@imports only)	AGENTS.md	hub file with markdown links per @import
CLAUDE.md (inline + @imports)	AGENTS.md	inline content preserved + @imports replaced with markdown links
.claude/agents/<name>.md (no @refs in body)	—	Cursor reads .claude/agents/ natively; no action needed
.claude/agents/<name>.md (has @refs in body)	.cursor/agents/<name>.md	wrapper with adapted frontmatter + @refs → markdown links
.claude/skills/<name>/SKILL.md	.cursor/skills/<name>/SKILL.md	transformed copy with adapted frontmatter + @refs → markdown links

Steps

1. Discover Claude Code config files

Run all discovery commands:

! readlink CLAUDE.md 2>/dev/null && echo "(CLAUDE.md is a symlink)" || echo "(CLAUDE.md is not a symlink)" ! ls CLAUDE.md 2>/dev/null || echo "(no CLAUDE.md)" ! ls .claude/agents/.md 2>/dev/null || echo "(no claude agents)" ! ls .claude/skills//SKILL.md 2>/dev/null || echo "(no claude skills)"

Then check for conflicts with existing Cursor configs:

! ls AGENTS.md 2>/dev/null || echo "(no existing AGENTS.md)" ! ls .cursor/agents/.md 2>/dev/null || echo "(no existing cursor agents)" ! ls .cursor/skills//SKILL.md 2>/dev/null || echo "(no existing cursor skills)"

2. Analyze and build the migration plan

For each discovered file:

• Read its content to extract YAML frontmatter (name, description, model, tools, background, argument-hint, etc.)
• Determine the strategy from the mapping table above
• Check if the target file already exists (conflict)

CLAUDE.md strategy decision:

1. If CLAUDE.md is a symlink to AGENTS.md or .cursorrules → Case A: already compatible, nothing to do
2. If CLAUDE.md is plain markdown with no @ references → Case B: symlink AGENTS.md → CLAUDE.md
3. If CLAUDE.md contains only @path/to/file lines (possibly with surrounding text) → Case C: create AGENTS.md hub by replacing each @path/to/file with [filename](path/to/file)
4. If CLAUDE.md contains a mix of inline content and @ imports → Case D: preserve inline content, replace each @path/to/file with [filename](path/to/file)

If AGENTS.md already exists (Cases B/C/D), flag it as a conflict and offer the user three options:

• overwrite: replace with the new file
• merge: append the new content to the existing file
• skip: leave AGENTS.md unchanged and note it in the report

Subagent strategy decision (per agent):

1. Read the agent body. Check for circular wrappers: if the body is a single @ import pointing to a path under .cursor/, skip it (already a wrapper around a Cursor original).
2. Scan the body for @path/to/file patterns.
3. If the body has no @ references → no action: Cursor reads .claude/agents/ natively with lower priority than .cursor/agents/. Unknown Claude frontmatter fields are ignored by Cursor.
4. If the body has @ references → create .cursor/agents/<name>.md wrapper (takes priority over .claude/agents/).

Skill strategy decision (per skill):

1. Skip skills in the exclusion list: migrate-cursor, migrate-to-cursor.
2. Check for circular wrappers: if the body is a single @ import pointing to a path under .cursor/ or .agents/, skip it.
3. All remaining skills → create .cursor/skills/<name>/SKILL.md transformed copy.

Subagent model mapping (Claude model: → Cursor model:):

• sonnet → fast
• opus → slow
• haiku → omit (note in report)
• anything else / not set → omit

Subagent field mapping:

• background: true → omit (no Cursor equivalent; note in report)
• tools: <list> → omit (no Cursor equivalent; note in report). Exception: if tools lists only Read, Glob, and/or Grep (no Edit, Write, Bash, WebFetch, WebSearch), map to readonly: true
• maxTurns, memory, effort, color, permissionMode → omit (note in report)

Skill field mapping:

• argument-hint → omit (no Cursor equivalent; note in report)

@ reference conversion (applied in AGENTS.md body, subagent wrappers, and skill copies):

Replace every occurrence of @path/to/file with [filename](path/to/file) where filename is the last component of the path (e.g., @.aidocs/STRATEGY.md → [STRATEGY.md](.aidocs/STRATEGY.md)).

3. Present the migration plan

Show a formatted table to the user:

## Migration Plan

| Source | Target | Strategy | Notes |
|--------|--------|----------|-------|
| CLAUDE.md | AGENTS.md | markdown links hub | 2 @imports → 2 markdown links |
| .claude/agents/unit-tester.md | (none) | already Cursor-readable | no @refs in body |
| .claude/agents/refactorer.md | .cursor/agents/refactorer.md | wrapper + @→link | model: sonnet→fast; background lost; tools lost |
| .claude/skills/adr/SKILL.md | .cursor/skills/adr/SKILL.md | transformed copy | argument-hint lost; ! commands present |

Flag any:

• Conflicts: target file already exists — note it and ask whether to overwrite, merge, or skip
• Capability gaps: fields that have no Cursor equivalent (background, tools, argument-hint, ! commands)
• Skipped files: circular wrappers, excluded skills, empty bodies
• No-action agents: agents Cursor already reads natively from .claude/agents/

Ask the user to confirm before proceeding.

4. Create AGENTS.md

Case A — symlink detected: nothing to do.

Case B — plain CLAUDE.md, no @refs:

! ln -s CLAUDE.md AGENTS.md

Cases C/D — @imports (with or without inline content):

Create AGENTS.md by processing CLAUDE.md line by line: replace each @path/to/file with [filename](path/to/file), preserve all other content as-is.

Example (Case C, current repo):

- For general strategy guidelines read [STRATEGY.md](.aidocs/STRATEGY.md)
- For project-specific details read [PROJECT.md](.aidocs/PROJECT.md)

5. Create subagent wrappers

Only for agents whose body contains @ references (agents without @refs are already Cursor-readable from .claude/agents/):

1. Parse frontmatter: name, description, model, background, tools
2. Build Cursor frontmatter using the mappings from Step 2
3. Convert body: replace all @path/to/file with [filename](path/to/file)
4. Create .cursor/agents/<name>.md:

---
name: <name>
description: <description>
[model: <mapped-value>]
[readonly: true]
---
<body with @refs converted to markdown links>

Create the .cursor/agents/ directory if it does not exist.

6. Create skill wrappers

For each .claude/skills/<name>/SKILL.md (excluding migrate-cursor and migrate-to-cursor):

1. Parse frontmatter: name, description. Note argument-hint loss.
2. Convert body: replace all @path/to/file with [filename](path/to/file)
3. Create .cursor/skills/<name>/SKILL.md:

---
name: <name>
description: <description>
---
<body with @refs converted to markdown links>

Create the .cursor/skills/<name>/ directory if it does not exist.

7. Report results

List every file created or skipped, and include a short caveats section:

• Markdown links are not auto-loaded: Cursor won't auto-import files linked from AGENTS.md. The links serve as navigable references; Cursor must be explicitly asked to read them.
• Subagents without @refs need no wrapper: Cursor reads .claude/agents/ natively (lower priority than .cursor/agents/). Unknown Claude frontmatter fields (tools, background, etc.) are silently ignored.
• Subagent capability gaps: background, tools, maxTurns, memory, effort, color, permissionMode have no Cursor equivalent and were omitted.
• Read-only heuristic: if a subagent was mapped to readonly: true, verify this is appropriate for its intended behavior.
• Skills are transformed copies: .cursor/skills/ files are copies of the Claude originals, not references. Claude skill remains the source of truth — edit there and re-run migration to sync.
• Shell command blocks: Claude skills use inline shell execution syntax — Cursor has no equivalent; these blocks appear as literal text.
• Argument hints lost: Claude skill argument-hint has no Cursor equivalent.
• Model mapping: if any Claude model: values were not recognized, they were omitted.

Guidelines

• Avoid content duplication: prefer no-action or symlinks when possible. Subagents without @refs need no wrapper — Cursor already reads them.
• Never overwrite without asking: if a target file already exists, present it as a conflict in the plan and ask the user whether to overwrite, merge, or skip.
• Skip empty bodies: if a skill or agent has no markdown body (frontmatter only), skip it and note it in the report.
• Idempotent: if run again on an already-migrated repo, detect existing Cursor files as conflicts and detect circular wrappers rather than silently overwriting.
• Claude files remain the source of truth: all edits should be made to the original Claude files; Cursor files should be regenerated by re-running this skill.