How to Convert Claude Code Plugins to Cursor IDE Format: A Complete Guide

Use the compound-plugin convert CLI command with the --to cursor flag to automatically transform Claude Code plugin manifests, agents, and skills into the .cursor directory structure required by Cursor IDE.

The EveryInc/compound-engineering-plugin repository provides a robust CLI tool that bridges the gap between Claude Code and Cursor IDE plugin ecosystems. If you need to convert Claude Code plugins to Cursor IDE format, this open-source converter handles the complex mapping of agents to rules, commands to markdown files, and MCP server configurations automatically.

Core Conversion Architecture

The conversion process relies on three primary components working in sequence to parse, transform, and materialize plugin assets.

The Conversion Pipeline

1. convertClaudeToCursor – Located in src/converters/claude-to-cursor.ts, this function maps Claude agents, commands, skills, and MCP servers into a structured CursorBundle object.

2. writeCursorBundle – Implemented in src/targets/cursor.ts, this function materializes the bundle as a .cursor directory containing rules/, commands/, skills/, and an optional mcp.json file.

3. convert command – Defined in src/commands/convert.ts, this CLI entry point loads the Claude plugin, selects the cursor target, runs the converter, and writes the output.

Step-by-Step Execution Flow

Step	Code Location	Operation
Load	src/parsers/claude.ts	Recursively reads manifest.yml and source files, building a ClaudePlugin object containing agents, commands, skills, and MCP servers.
Select	src/commands/convert.ts → src/targets/index.ts	Looks up the cursor handler in the targets registry. targets["cursor"] returns a TargetHandler with convert and write methods.
Transform	src/converters/claude-to-cursor.ts	Converts agents to Cursor rules via convertAgentToRule, commands to Cursor commands via convertCommand, and MCP servers to Cursor-compatible JSON. Uses uniqueName, normalizeName, and transformContentForCursor helpers.
Write	src/targets/cursor.ts → writeCursorBundle	Creates <outputRoot>/.cursor/ directory, writing rules/*.mdc, commands/*.md, skills/* (copied verbatim), and mcp.json. Uses utilities from src/utils/files.ts for safe file operations.
Feedback	src/commands/convert.ts	Prints success messages and handles additional targets via the --also flag.

Content Transformation Rules

The transformContentForCursor function in src/converters/claude-to-cursor.ts rewrites Claude-specific syntax to Cursor-compatible formats:

Claude Pattern	Cursor Replacement
Task agent-name(args)	Use the <skill> skill to: args
/namespace:command	Flattened to /command
~/.claude/… or .claude/…	Rewritten to ~/.cursor/… or .cursor/…
@my‑agent‑specialist	Referenced as the <normalized‑name> rule

These transformations ensure that generated Markdown files work out-of-the-box inside Cursor's rule engine without manual editing.

Practical Usage Examples

Basic Conversion

Convert a Claude plugin to Cursor format with a single command:

compound-plugin convert ./my-claude-plugin \
  --to cursor \
  --output ./my-project

This creates ./my-project/.cursor/ with the following structure:

.cursor/
├─ commands/
│  └─ my-command.md
├─ rules/
│  └─ my-agent.mdc
├─ skills/
│  └─ my-skill/   (copied verbatim)
└─ mcp.json        (optional)

Converting Multiple Formats

Generate both Cursor and Codex bundles simultaneously:

compound-plugin convert ./my-claude-plugin \
  --to cursor \
  --also codex \
  --output ./my-project

The CLI first writes the Cursor bundle to ./my-project/.cursor/, then produces a Codex bundle under ./my-project/codex/.

Custom Output Locations

Target an existing .cursor directory directly:

compound-plugin convert ./my-claude-plugin \
  --to cursor \
  --output /tmp/cursor-output

If --output points to an existing .cursor directory, the resolveCursorPaths helper in src/targets/cursor.ts places files directly inside it without creating a nested subdirectory.

Key Implementation Files

File	Role
src/converters/claude-to-cursor.ts	Core conversion logic, name normalization via uniqueName and normalizeName, and content transformation.
src/targets/cursor.ts	Implements writeCursorBundle to materialize the CursorBundle as a .cursor directory with rules/, commands/, skills/, and mcp.json.
src/types/cursor.ts	TypeScript definitions for CursorRule, CursorCommand, skill directories, and MCP server configurations.
src/commands/convert.ts	CLI command entry point that orchestrates loading, converting, and writing via the target handler pattern.
src/targets/index.ts	Registry mapping the cursor target name to its handler implementation.
src/utils/files.ts	Utility functions for safe filesystem operations including ensureDir, writeText, and backupFile.

Summary

• The compound-engineering-plugin CLI provides a complete pipeline to convert Claude Code plugins to Cursor IDE format using the convert command with --to cursor.
• Three core components handle the transformation: convertClaudeToCursor for mapping structures, writeCursorBundle for disk output, and the convert command for orchestration.
• Automatic syntax rewriting via transformContentForCursor adapts Claude-specific patterns like Task calls and slash commands to Cursor-compatible rules and commands.
• Output structure follows Cursor IDE conventions with .cursor/rules/*.mdc, .cursor/commands/*.md, .cursor/skills/, and optional .cursor/mcp.json.

Frequently Asked Questions

How do I install the compound-engineering-plugin CLI?

The repository provides installation instructions in its README. Typically, you clone the EveryInc/compound-engineering-plugin repository and install dependencies via npm install or yarn install, then build the TypeScript source. The CLI becomes available as compound-plugin after installation.

What happens to Claude agents during conversion?

Claude agents are transformed into Cursor rules using the convertAgentToRule function in src/converters/claude-to-cursor.ts. Each agent becomes a .mdc file in the .cursor/rules/ directory with appropriate front-matter metadata that Cursor recognizes as project rules.

Can I convert plugins that use MCP servers?

Yes. The converter handles MCP server configurations by extracting them from the Claude plugin manifest and writing them to .cursor/mcp.json. The transformContentForCursor function also rewrites any Claude-specific MCP references to use Cursor-compatible syntax patterns.

Is it possible to customize the output directory structure?

The writeCursorBundle function in src/targets/cursor.ts uses the resolveCursorPaths helper to determine output locations. While the standard structure places files under .cursor/, you can direct output to any path using the --output flag. If the target path already ends with .cursor, files are written directly into that directory rather than creating a nested structure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}