Migrate cursor

Migrate Cursor

Migrate workspace skills, rules, and configuration from a Cursor setup to Claude Code. This skill runs in two phases:

1. Export (run in Cursor) — scans .cursor/ for local skills, rules, and config, then writes a portable .cursor-export.md file.
2. Import (run in Claude Code) — reads the export file (or .cursor/ directly), creates .claude/, and recreates all artifacts in Claude Code format.

Config dependency

This skill works without skills-config.yaml — it is designed to run before config exists in the target environment.

If skills-config.yaml exists in .cursor/, it will be migrated to .claude/.

Guardrails

1. Never delete or modify any files in .cursor/ — this is a non-destructive migration.
2. Never overwrite existing files in .claude/ or CLAUDE.md without explicit user confirmation.
3. Always show the user what will be created before writing.
4. If .cursor-export.md already exists, ask before overwriting.

Required Inputs

• Phase: Detect automatically based on context, or accept an explicit "export" / "import" instruction from the user.

Workflow

Step 1 — Detect phase

Check the workspace for:

ls .cursor/skills/*.skill 2>/dev/null
ls .cursor-export.md 2>/dev/null
ls .claude/ 2>/dev/null

Determine which phase to run:

Condition	Phase
.cursor/skills/*.skill files exist	Export (Step 2)
.cursor-export.md exists	Import (Step 5)
.cursor/ exists but no .skill files	Direct import (Step 5, reading from .cursor/ directly)
Neither .cursor/ nor .cursor-export.md exist	Nothing to migrate — tell the user

If the user explicitly says "export" or "import", follow their instruction regardless of auto-detection.

---

Export Phase (Steps 2–4)

Run this phase in Cursor to extract all local artifacts into a portable file.

Step 2 — Extract local Cursor skills

For each .skill file in .cursor/skills/:

1. The .skill format is a ZIP archive containing a SKILL.md and optional references/ files. Extract the SKILL.md:

unzip -p "<name>.skill" "*/SKILL.md"

2. List all files in the archive to find references:

unzip -l "<name>.skill"

3. For each reference file found, extract its content with unzip -p.

4. If extraction fails (corrupted or unsupported format), note the filename and skip it with a warning.

Step 3 — Read rules and config

1. Read all .cursor/rules/*.mdc files. For each, capture:
   • Frontmatter fields: description, alwaysApply, globs (if present)
   • The markdown body (everything after the closing ---)
2. Read .cursor/skills-config.yaml if it exists.
3. Read .cursor/settings.json for reference (note which plugins are enabled).

Step 4 — Write the export file

Combine everything into .cursor-export.md at the workspace root. Use the following structure so the import phase can parse it reliably:

# Cursor Export

Generated by sdlc-toolkit migrate-cursor on <YYYY-MM-DD>.

---

## Skills

### <skill-name>

<full SKILL.md content>

#### References

##### <reference-filename>

<reference file content>

---

[repeat for each skill]

## Rules

### <rule-filename>

| Field | Value |
|-------|-------|
| Description | <from frontmatter> |
| Always apply | <yes/no> |
| Globs | <glob pattern or "none"> |

<rule markdown body>

---

[repeat for each rule]

## Config

​```yaml
<full skills-config.yaml content>
​```

## Settings

​```json
<full settings.json content>
​```

After writing, tell the user:

Export complete. Open this workspace in Claude Code and run migrate cursor to complete the migration.

---

Import Phase (Steps 5–10)

Run this phase in Claude Code to recreate all artifacts.

Step 5 — Read source

Determine what to read:

1. If .cursor-export.md exists: parse it to extract skills, rules, and config sections. Use the ## Skills, ## Rules, ## Config headings as delimiters.
2. If no export file but .cursor/ exists (direct import): read directly:
   • .cursor/skills-config.yaml
   • .cursor/rules/*.mdc
   • Attempt to extract .cursor/skills/*.skill files via unzip -p. If the binary cannot be read (e.g., no unzip available), skip skills and warn the user.

Step 6 — Create .claude/ directory

1. Check if .claude/ already exists.
2. If it does and contains files, list them and ask the user: merge into existing, or skip conflicting files?
3. If it doesn't exist, create it:

mkdir -p .claude

Step 7 — Migrate skills-config.yaml

1. Read the config content (from export file or .cursor/skills-config.yaml).
2. Update the location comment if present:
   • Replace any Location: *.cursor/skills-config.yaml with Location: <workspace>/.claude/skills-config.yaml
3. Write to .claude/skills-config.yaml.
4. If .claude/skills-config.yaml already exists, show a diff and ask before overwriting.

Step 8 — Convert rules to CLAUDE.md

1. If CLAUDE.md exists at the workspace root, read its current content.
2. For each exported rule:
   • Drop the Cursor .mdc frontmatter format.
   • Convert the rule body into a plain markdown section with a descriptive heading.
   • If the rule has alwaysApply: true, include it as a top-level section.
   • If the rule has a globs pattern, add a note about which files it applies to.
3. Append all converted rules to CLAUDE.md (or create the file if it doesn't exist).
4. Show the user the resulting CLAUDE.md content before writing.

Step 9 — Recreate skill behaviors

For each exported skill:

1. Read the SKILL.md content and understand the skill's purpose, triggers, and workflow.
2. Summarize the skill's behavior into a concise instruction block suitable for CLAUDE.md.
3. Add under a # Local Skills heading in CLAUDE.md.

Keep each skill summary focused on what the agent should do — not how the original Cursor skill was structured. Adapt terminology:

• "Cursor" references → "Claude Code"
• .cursor/ paths → .claude/
• Cursor-specific features → Claude Code equivalents (or note if no equivalent exists)

4. Present to the user for review before writing.

Important: Migrated skills become static instructions — they are not executable slash-command skills. For equivalent interactive behavior, recommend the user creates a proper sdlc-toolkit skill using generate-skill.

Step 10 — Report

Present a migration summary.

Safety Rules

• Never modify or delete .cursor/ contents.
• Never overwrite existing .claude/ files or CLAUDE.md without user confirmation.
• Remind the user to add .cursor-export.md to .gitignore if it contains sensitive data (Slack IDs, project IDs, tokens).
• If skills-config.yaml contains secrets or tokens, warn the user before writing.

Output format

Export phase:

Export written to `.cursor-export.md`.

- Skills exported: <count> (<list of names>)
- Rules exported: <count> (<list of filenames>)
- Config: <included / not found>

Next: open this workspace in Claude Code and run `migrate cursor` to import.

Import phase:

Migration complete.

- `.claude/skills-config.yaml` — <created / updated / skipped>
- `CLAUDE.md` — <created / updated>
  - Rules migrated: <count> (<list>)
  - Skills migrated: <count> (<list>)
- Skipped: <list of items that could not be migrated, if any>

Tip: run `bootstrap-config` to verify and update the config for Claude Code.