Cursor Migration Guide

your-project/
├── .claude/
│   ├── rules/
│   │   ├── api-validation.md
│   │   └── legacy-cursor.md
│   └── skills/
│       ├── create-pr/
│       │   └── SKILL.md
│       └── security-review/
│           └── SKILL.md
├── .cursor/
│   ├── commands/
│   ├── rules/
│   └── mcp.json
├── scripts/
│   └── migrate-cursor-config.mjs
├── .mcp.json
├── AGENTS.md
└── CLAUDE.md

# Project instructions

## Repository map

- `apps/web` is the Next.js 16 application.
- `packages/database` owns schema and migrations.
- `packages/ui` owns shared React components.

## Commands

- Install with `pnpm install --frozen-lockfile`.
- Run the nearest package test while editing.
- Run `pnpm lint && pnpm typecheck && pnpm test` before completion.

## Boundaries

- Do not edit generated files.
- Never run production migrations from an agent session.
- Shared code belongs in `packages`, not another app's private directory.

@AGENTS.md

# Claude Code

- Read the nearest nested `CLAUDE.md` before editing a package.
- Use package-filtered checks during implementation.
- Report any verification command that could not run.

import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
import path from "node:path";

const root = process.cwd();
const writeChanges = process.argv.includes("--write");
const includeMcp = process.argv.includes("--include-mcp");
const planned = [];
const warnings = [];
const ignoredDirectories = new Set([
  ".git",
  ".claude",
  ".next",
  ".turbo",
  "coverage",
  "dist",
  "node_modules",
]);

function splitFrontmatter(source) {
  if (!source.startsWith("---\n")) {
    return { data: {}, body: source.trim(), parseWarnings: [] };
  }

  const end = source.indexOf("\n---\n", 4);
  if (end === -1) {
    return {
      data: {},
      body: source.trim(),
      parseWarnings: ["frontmatter has no closing delimiter"],
    };
  }

  const header = source.slice(4, end);
  const body = source.slice(end + 5).trim();
  const data = {};
  const parseWarnings = [];
  let currentKey = null;

  for (const rawLine of header.split("\n")) {
    const line = rawLine.trim();
    if (!line || line.startsWith("#")) continue;

    const listItem = rawLine.match(/^\s+-\s+(.+)$/);
    if (listItem && currentKey) {
      if (!Array.isArray(data[currentKey])) data[currentKey] = [];
      data[currentKey].push(listItem[1].trim().replace(/^["']|["']$/g, ""));
      continue;
    }

    const separator = line.indexOf(":");
    if (separator === -1) continue;

    const key = line.slice(0, separator).trim();
    let value = line.slice(separator + 1).trim();
    currentKey = key;

    if (value === "|" || value === ">") {
      parseWarnings.push(`multiline ${key} must be reviewed manually`);
      continue;
    }

    value = value.replace(/^["']|["']$/g, "");

    if (value === "true") value = true;
    if (value === "false") value = false;
    data[key] = value;
  }

  return { data, body, parseWarnings };
}

function parseGlobs(value) {
  if (Array.isArray(value)) return value.filter(Boolean);
  if (typeof value !== "string" || value.trim() === "") return [];

  const unwrapped = value.replace(/^\[/, "").replace(/\]$/, "");
  return unwrapped
    .split(",")
    .map((item) => item.trim().replace(/^["']|["']$/g, ""))
    .filter(Boolean);
}

function yamlString(value) {
  return JSON.stringify(value);
}

function safeName(value) {
  const name = value
    .toLowerCase()
    .replace(/[^a-z0-9-]+/g, "-")
    .replace(/^-+|-+$/g, "")
    .slice(0, 64);

  if (!name) throw new Error(`Cannot create a safe name from ${value}`);
  return name;
}

async function exists(file) {
  try {
    await stat(file);
    return true;
  } catch {
    return false;
  }
}

async function planFile(relativeTarget, content, source) {
  const target = path.join(root, relativeTarget);

  if (
    (await exists(target)) ||
    planned.some((item) => item.relativeTarget === relativeTarget)
  ) {
    warnings.push(`SKIP ${relativeTarget}: target already exists`);
    return;
  }

  planned.push({ target, relativeTarget, content, source });
}

async function listFiles(directory, extension) {
  if (!(await exists(directory))) return [];

  const entries = await readdir(directory, { withFileTypes: true });
  return entries
    .filter((entry) => entry.isFile() && entry.name.endsWith(extension))
    .map((entry) => path.join(directory, entry.name))
    .sort();
}

async function findCursorRules(directory = root) {
  const entries = await readdir(directory, { withFileTypes: true });
  const files = [];

  for (const entry of entries) {
    if (!entry.isDirectory() || ignoredDirectories.has(entry.name)) continue;

    const child = path.join(directory, entry.name);
    if (entry.name === ".cursor") {
      files.push(...(await listFiles(path.join(child, "rules"), ".mdc")));
      continue;
    }

    files.push(...(await findCursorRules(child)));
  }

  return files.sort();
}

async function convertRule(file) {
  const source = await readFile(file, "utf8");
  const { data, body, parseWarnings } = splitFrontmatter(source);
  const relativeSource = path.relative(root, file).split(path.sep).join("/");
  const marker = "/.cursor/rules/";
  const markedSource = `/${relativeSource}`;
  const markerIndex = markedSource.lastIndexOf(marker);
  const scope = markedSource.slice(1, markerIndex);
  const rawName = [scope, path.basename(file, ".mdc")]
    .filter(Boolean)
    .join("-");
  const name = safeName(rawName);
  const globs = parseGlobs(data.globs);

  if (parseWarnings.length > 0) {
    warnings.push(
      `SKIP ${relativeSource}: ${parseWarnings.join(", ")}`,
    );
    return;
  }

  if (/^\s*@\S+/m.test(body)) {
    warnings.push(
      `SKIP ${relativeSource}: Cursor @file references need a manual path review`,
    );
    return;
  }

  if (scope && globs.length > 0) {
    warnings.push(
      `SKIP ${relativeSource}: combine its nested directory scope and globs manually`,
    );
    return;
  }

  if (data.alwaysApply === true && !scope) {
    await planFile(
      `.claude/rules/${name}.md`,
      `${body}\n`,
      relativeSource,
    );
    return;
  }

  if (globs.length > 0 || scope) {
    const scopedGlobs = globs.length > 0 ? globs : [`${scope}/**`];
    const paths = scopedGlobs
      .map((glob) => `  - ${yamlString(glob)}`)
      .join("\n");
    await planFile(
      `.claude/rules/${name}.md`,
      `---\npaths:\n${paths}\n---\n\n${body}\n`,
      relativeSource,
    );
    return;
  }

  const description =
    typeof data.description === "string" && data.description
      ? data.description
      : `Run the migrated ${name} workflow when the user invokes it.`;
  await planFile(
    `.claude/skills/${name}/SKILL.md`,
    `---\ndescription: ${yamlString(description)}\ndisable-model-invocation: true\n---\n\n${body}\n`,
    relativeSource,
  );
}

async function convertCommand(file) {
  const source = (await readFile(file, "utf8")).trim();
  const name = safeName(path.basename(file, ".md"));

  if (/^\s*@\S+/m.test(source)) {
    warnings.push(
      `SKIP ${path.relative(root, file)}: Cursor @file references need a manual path review`,
    );
    return;
  }

  await planFile(
    `.claude/skills/${name}/SKILL.md`,
    [
      "---",
      `description: ${yamlString(`Run the migrated Cursor ${name} workflow.`)}`,
      "disable-model-invocation: true",
      "---",
      "",
      source,
      "",
    ].join("\n"),
    path.relative(root, file),
  );
}

async function convertLegacyRules() {
  const file = path.join(root, ".cursorrules");
  if (!(await exists(file))) return;

  const source = (await readFile(file, "utf8")).trim();
  await planFile(
    ".claude/rules/legacy-cursor.md",
    `${source}\n`,
    ".cursorrules",
  );
}

async function convertMcp() {
  if (!includeMcp) return;

  const sourceFile = path.join(root, ".cursor", "mcp.json");
  if (!(await exists(sourceFile))) return;

  const source = await readFile(sourceFile, "utf8");
  const parsed = JSON.parse(source);

  if (
    typeof parsed !== "object" ||
    parsed === null ||
    typeof parsed.mcpServers !== "object" ||
    parsed.mcpServers === null
  ) {
    throw new Error(".cursor/mcp.json has no mcpServers object");
  }

  const secretPattern = /(token|secret|password|api[_-]?key)/i;
  if (secretPattern.test(source)) {
    warnings.push(
      "MCP config contains a secret-like name. Confirm values use environment variables.",
    );
  }

  await planFile(
    ".mcp.json",
    `${JSON.stringify(parsed, null, 2)}\n`,
    ".cursor/mcp.json",
  );
}

const cursorRules = await findCursorRules();
const cursorCommands = await listFiles(
  path.join(root, ".cursor", "commands"),
  ".md",
);

await convertLegacyRules();
for (const file of cursorRules) await convertRule(file);
for (const file of cursorCommands) await convertCommand(file);
await convertMcp();

for (const item of planned) {
  console.log(
    `${writeChanges ? "WRITE" : "PLAN "} ${item.relativeTarget} <- ${item.source}`,
  );

  if (writeChanges) {
    await mkdir(path.dirname(item.target), { recursive: true });
    await writeFile(item.target, item.content, { flag: "wx" });
  }
}

for (const warning of warnings) console.warn(warning);

if (!writeChanges) {
  console.log("\nDry run only. Re-run with --write after reviewing the plan.");
}
if (!includeMcp) {
  console.log(
    "MCP was not copied. Add --include-mcp only after reviewing server commands and secrets.",
  );
}

node scripts/migrate-cursor-config.mjs

node scripts/migrate-cursor-config.mjs --write

node scripts/migrate-cursor-config.mjs --write --include-mcp