Convert rules between Cursor, Windsurf, and Claude Code

Bidirectional conversion between .mdc, .cursorrules, CLAUDE.md, and Windsurf formats.

What rule-porter does

Different AI editors use different rule formats. rule-porter converts between them so you can switch editors without rewriting your rules from scratch.

Supported formats:

• Cursor: .mdc files with YAML frontmatter in .cursor/rules/
• Cursor (legacy): .cursorrules single file
• Claude Code: CLAUDE.md in project root
• AGENTS.md: Multi-agent instructions
• Windsurf: .windsurfrules
• GitHub Copilot: .github/copilot-instructions.md

Running the command

The tool auto-detects your source format and prompts you to choose a target:

npx rule-porter

Or specify source and target explicitly:

npx rule-porter --from cursor --to claude-md

The converter reads your rules, translates them to the target format, and writes the output to the appropriate location for that editor.

Direction flags

Use --from and --to to control conversion direction:

npx rule-porter --from cursor --to windsurf
npx rule-porter --from claude-md --to cursor
npx rule-porter --from cursorrules-legacy --to cursor

Supported values:

• cursor — .cursor/rules/*.mdc files
• cursorrules-legacy — legacy single .cursorrules file
• claude-md — CLAUDE.md
• agents-md — AGENTS.md
• windsurf — .windsurfrules
• copilot — .github/copilot-instructions.md

What gets translated

The converter handles format differences automatically:

Frontmatter to comments

Cursor's YAML frontmatter becomes comments in formats that don't support structured metadata:

# From .mdc frontmatter:
---
description: TypeScript naming conventions
globs: ["**/*.ts"]
---

# To CLAUDE.md:
# Rule: TypeScript naming conventions
# Applies to: **/*.ts

Globs to file paths

Some formats don't support globs. The converter notes where a rule was intended to apply but can't enforce scoping in the target format.

Multiple files to single file

When converting from .mdc (multiple files) to CLAUDE.md (single file), the tool merges all rules with section headers based on the original filenames.

All conversions are free

Every conversion direction is included for free, including:

• .mdc ↔ CLAUDE.md
• .mdc ↔ AGENTS.md
• .cursorrules → .mdc
• Windsurf ↔ Cursor
• Copilot ↔ Cursor

Use --dry-run to preview the output before writing files.

Checking the output

After conversion, check the output manually. The tool handles structure but can't guarantee every rule makes sense in the target editor's context.

• Cursor output: Run npx cursor-doctor scan to validate frontmatter
• Claude Code output: Open CLAUDE.md and verify sections are readable
• Windsurf output: Check .windsurf/rules/ or .windsurfrules in the editor

Limits of conversion

Some things don't translate perfectly between formats:

• Globs: Editors without glob support can't scope rules to specific files. The converter preserves the intent in comments but can't enforce it.
• alwaysApply: Not all formats have an equivalent. Rules may load differently in the target editor.
• Rule references: If your rules reference each other by name (@rulename), these might break after conversion if filenames change.

When to use it

The converter is useful when:

• You're switching editors and want to port existing rules
• You're trying multiple editors and want the same rules in each
• You found a good CLAUDE.md example and want it in Cursor format
• You're migrating a team from one editor to another

It's a starting point, not a perfect translation. Expect to refine the output manually.

Related guides

• Migrating from .cursorrules to .mdc files
• Generate Cursor rules from your codebase with AI
• How to write Cursor rules that actually work

npx rule-porter