migrate-to-cc

Migrate Cursor / VS Copilot Configurations to Claude Code

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

Mapping rules

Source	Claude equivalent	Strategy
AGENTS.md	CLAUDE.md	symlink (if sole source) or @import (if multiple sources)
.cursorrules	CLAUDE.md	symlink (if sole source) or @import
.github/copilot-instructions.md	CLAUDE.md	@import
.cursor/rules/*.mdc	CLAUDE.md	@import with original glob as comment
.cursor/agents/*.md	.claude/agents/<name>.md	wrapper with adapted frontmatter + @import body
.cursor/skills/*.md	.claude/skills/<name>/SKILL.md	wrapper with adapted frontmatter + @import body

Steps

1. Discover Cursor / Copilot config files

Run all discovery commands:

! ls AGENTS.md .cursorrules .github/copilot-instructions.md 2>/dev/null ! ls .cursor/rules/.mdc 2>/dev/null || echo "(no .mdc rules)" ! ls .cursor/agents/.md 2>/dev/null || echo "(no cursor agents)" ! ls .cursor/skills/*.md 2>/dev/null || echo "(no cursor skills)"

Then check for conflicts with existing Claude Code configs:

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

2. Analyze and build the migration plan

For each discovered file:

• Read its YAML frontmatter to extract metadata (description, globs, alwaysApply, name, model, is_background, etc.)
• Determine the strategy from the mapping table above
• Check if the target file already exists (conflict)

CLAUDE.md strategy decision:

• Count the "instruction sources": AGENTS.md, .cursorrules, .github/copilot-instructions.md, .cursor/rules/*.mdc
• If exactly 1 source and it is AGENTS.md or .cursorrules: use a symlink
• If 2 or more sources: use a hub file with @imports

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

• fast → sonnet
• slow or large → opus
• anything else / not set → omit the field (Claude inherits from parent)

Agent background mapping:

• is_background: true → background: true
• not set → omit the field

3. Present the migration plan

Show a formatted table to the user:

## Migration Plan

| Source | Target | Strategy | Notes |
|--------|--------|----------|-------|
| AGENTS.md | CLAUDE.md | symlink | |
| .cursor/rules/domain-layer.mdc | CLAUDE.md | @import | glob: src/**/domain/**/*.ts (scope lost) |
| .cursor/agents/unit-tester.md | .claude/agents/unit-tester.md | wrapper + @import | model: fast → sonnet |
| .cursor/agents/refactorer.md | .claude/agents/refactorer.md | wrapper + @import | is_background → background: true |

Flag any:

• Conflicts: target file already exists — note it and ask whether to overwrite or skip
• Capability gaps: glob-scoped rules become always-loaded; background mode may differ
• Skipped files: .mdc files with empty body (frontmatter only)

Ask the user to confirm before proceeding.

4. Create CLAUDE.md

Symlink case (single source, AGENTS.md or .cursorrules):

! ln -s AGENTS.md CLAUDE.md

Hub file case (multiple sources):

Create CLAUDE.md with one @import per source. For .mdc rules, include a comment with the original description and globs / alwaysApply values so future readers understand the intended scope:

@AGENTS.md

<!-- Rule: {description} | Originally scoped to: {globs or "alwaysApply"} -->
@.cursor/rules/project-structure.mdc

<!-- Rule: {description} | Originally scoped to: {globs} -->
@.cursor/rules/domain-layer.mdc

Order imports: instruction files first (AGENTS.md, .cursorrules, copilot-instructions), then .mdc rules sorted by alwaysApply: true first, then alphabetically.

5. Create agent wrappers

For each .cursor/agents/<name>.md:

1. Parse frontmatter: name, description, model, is_background
2. Build Claude frontmatter:
   • name: same as Cursor
   • description: same as Cursor
   • model: apply mapping from Step 2 (omit if no mapping needed)
   • background: true if Cursor had is_background: true (omit otherwise)
3. Create .claude/agents/<name>.md:

---
name: <name>
description: <description>
[model: <mapped-value>]
[background: true]
---
@.cursor/agents/<name>.md

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

6. Create skill wrappers

For each .cursor/skills/<name>.md (if any exist):

1. Parse frontmatter: name, description, and any argument-hint equivalent
2. Create .claude/skills/<name>/SKILL.md with Claude-compatible frontmatter + @import:

---
name: <name>
description: <description>
[argument-hint: <hint if present>]
---
@.cursor/skills/<name>.md

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

7. Report results

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

• Glob rules are always-loaded: .mdc rules originally scoped to specific file patterns are now loaded into every Claude conversation. The original glob is preserved as a comment in CLAUDE.md for reference.
• Review agent wrappers: Claude agents support additional fields (tools, maxTurns, memory, effort, color, permissionMode) that may improve the agent experience — the wrappers intentionally omit them to keep defaults, but the user may want to customize them.
• Model mapping: if any Cursor model: values were not recognized, they were passed through as-is and may need manual correction.

Guidelines

• Never duplicate content: the originals (AGENTS.md, .mdc files, cursor agents) remain the single source of truth. All Claude Code files are thin wrappers or import hubs.
• Never overwrite without asking: if a target file already exists, always present it as a conflict in the plan and ask the user whether to overwrite or skip.
• Skip empty bodies: if a .mdc file has no markdown body (frontmatter only), skip it and note it in the report.
• Idempotent: if run again on an already-migrated repo, the tool should detect the existing Claude files and report them as conflicts rather than silently overwriting.