rule-porter

Convert AI IDE rules between Cursor, Claude Code, GitHub Copilot, Windsurf, and AGENTS.md. Bidirectional. Zero dependencies.

npx rule-porter --to agents-md

Why?

Your AI coding rules are locked into whatever tool you wrote them for. Cursor uses .mdc files with YAML frontmatter and glob patterns. Claude Code uses CLAUDE.md. Copilot uses .github/copilot-instructions.md. Windsurf uses .windsurfrules. None of them understand each other's format.

rule-porter converts between all of them, preserving as much structure as possible and warning you about anything that can't convert cleanly.

Supported Formats

| Format | As Source | As Target | File | |--------|-----------|-----------|------| | Cursor | ✅ | ✅ | .cursor/rules/*.mdc | | Cursor (legacy) | ✅ | — | .cursorrules | | AGENTS.md | ✅ | ✅ | AGENTS.md | | Claude Code | ✅ | ✅ | CLAUDE.md | | GitHub Copilot | ✅ | ✅ | .github/copilot-instructions.md | | Windsurf | ✅ | ✅ | .windsurfrules |

Usage

Run from your project root:

# Convert Cursor rules to other formats
npx rule-porter --to agents-md
npx rule-porter --to claude-md
npx rule-porter --to copilot
npx rule-porter --to windsurf

# Convert OTHER formats to Cursor .mdc rules
npx rule-porter --from agents-md --to cursor
npx rule-porter --from claude-md --to cursor
npx rule-porter --from copilot --to cursor
npx rule-porter --from windsurf --to cursor

# Migrate legacy .cursorrules to .mdc
npx rule-porter --from cursorrules-legacy --to cursor

# Convert between any two formats
npx rule-porter --from agents-md --to claude-md

# Preview without writing files
npx rule-porter --to agents-md --dry-run

# Custom output path
npx rule-porter --to claude-md --out ./docs/CLAUDE.md

Options

| Flag | Description | |------|-------------| | --to <format> | Target format (required) | | --from <format> | Source format (default: auto-detect) | | --out <path> | Output file path (default: format's standard location) | | --dry-run | Preview the output without writing any files | | --help | Show help | | --version | Show version |

What Gets Converted

Preserved

• Rule names and descriptions
• Rule body content (markdown, code blocks, everything)
• Global vs conditional rule separation
• alwaysApply rules become top-level/global sections
• Glob patterns restored when converting back to Cursor

Converted with Warnings

• Glob patterns — flat markdown formats don't support file scoping. rule-porter keeps them as human-readable comments and warns you.
• alwaysApply flag — mapped to document structure (global section vs conditional section).
• Manual-attach rules — rules with no globs and not alwaysApply get flagged for review.

Skipped

• Empty files
• Files with only frontmatter and no body content
• Unreadable files (permission errors)

Example

Given Cursor rules, npx rule-porter --to agents-md produces:

# AGENTS.md

> Generated by rule-porter from .cursor/rules/

## Global Rules

### General guidelines

Use conventional commits. Write tests for new features.

## Conditional Rules

### TypeScript standards

*Applies to: `**/*.ts`*

Use strict TypeScript. No any types.

Converting back: npx rule-porter --from agents-md --to cursor produces individual .mdc files with frontmatter, globs, and alwaysApply flags restored.

Lossy Conversions

Some features don't have equivalents across formats. rule-porter handles these honestly:

• Glob patterns become markdown comments in flat formats. Warning for each one.
• alwaysApply becomes structural (section placement). Intent preserved, mechanism differs.
• No silent data loss. Every non-1:1 conversion produces a warning.

Related

Part of the nedcodes toolkit for Cursor AI developers.

• rule-gen — Generate rules from your codebase using Google Gemini. npx rulegen-ai
• cursor-doctor — Diagnose and fix broken Cursor rules. Scans your .cursor/rules/ for missing frontmatter, invalid globs, conflicts, and more. npx cursor-doctor scan

Roadmap

• [ ] Batch conversion (all formats at once)
• [ ] Config file for custom format mappings

License

MIT