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

> Easily convert Claude Code plugins to Cursor IDE format. Use the compound-plugin convert CLI command with the --to cursor flag for a seamless transformation of manifests, agents, and skills.

- Repository: [Every/compound-engineering-plugin](https://github.com/everyinc/compound-engineering-plugin)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/targets/cursor.ts), this function materializes the bundle as a `.cursor` directory containing `rules/`, `commands/`, `skills/`, and an optional [`mcp.json`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/mcp.json) file.

3. **`convert` command** – Defined in [`src/commands/convert.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/parsers/claude.ts) | Recursively reads [`manifest.yml`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/manifest.yml) and source files, building a `ClaudePlugin` object containing agents, commands, skills, and MCP servers. |
| **Select** | [`src/commands/convert.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/commands/convert.ts) → [`src/targets/index.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/targets/cursor.ts) → `writeCursorBundle` | Creates `<outputRoot>/.cursor/` directory, writing `rules/*.mdc`, `commands/*.md`, `skills/*` (copied verbatim), and [`mcp.json`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/mcp.json). Uses utilities from [`src/utils/files.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/utils/files.ts) for safe file operations. |
| **Feedback** | [`src/commands/convert.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-cursor.ts)** | Core conversion logic, name normalization via `uniqueName` and `normalizeName`, and content transformation. |
| **[`src/targets/cursor.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/targets/cursor.ts)** | Implements `writeCursorBundle` to materialize the `CursorBundle` as a `.cursor` directory with `rules/`, `commands/`, `skills/`, and [`mcp.json`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/mcp.json). |
| **[`src/types/cursor.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/types/cursor.ts)** | TypeScript definitions for `CursorRule`, `CursorCommand`, skill directories, and MCP server configurations. |
| **[`src/commands/convert.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/commands/convert.ts)** | CLI command entry point that orchestrates loading, converting, and writing via the target handler pattern. |
| **[`src/targets/index.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/targets/index.ts)** | Registry mapping the `cursor` target name to its handler implementation. |
| **[`src/utils/files.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/.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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/.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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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.