Conversion

Convert Claude Code plugins to work with other AI coding tools.

Overview

The convert command takes a Claude Code plugin directory and produces equivalent configuration for other tools. Supported targets:

Target	Tool	Output
codex	OpenAI Codex	.codex/skills/ plus .codex/ config, prompts, and hooks
cursor	Cursor	.cursor/ dir with rules + MCP config
opencode	OpenCode	opencode.json + .opencode/ skills dir
pi	Pi	.pi/ dir with skills, prompt templates, and extensions

Each target gets the closest equivalent of your plugin's skills, commands, hooks, MCP servers, and LSP servers — with diagnostics when something can't convert cleanly.

Quick Start

Convert a plugin to all targets:

ai-config convert ./my-plugin

Convert to a specific target:

ai-config convert ./my-plugin --target codex

Preview without writing files:

ai-config convert ./my-plugin --dry-run

Sync-Driven Conversion

Instead of running convert manually, you can configure automatic conversion in your config file. Every time ai-config sync runs, it converts all synced plugins to the specified targets.

version: 1
targets:
  - type: claude
    config:
      marketplaces:
        my-plugins:
          source: github
          repo: myorg/my-plugins

      plugins:
        - id: my-tool@my-plugins
          scope: user
          enabled: true

      conversion:
        enabled: true
        targets:
          - codex
          - cursor
        scope: project

With this config, ai-config sync installs your Claude plugins and then converts them to Codex and Cursor format.

Target-Native Files

Most plugin content should flow through the normal converter. When a target needs hand-written files that cannot be generated cleanly, place them under targets/<target>/ in the plugin source:

my-plugin/
├── .claude-plugin/plugin.json
├── skills/my-skill/SKILL.md
└── targets/pi/extensions/my-plugin-hooks.ts

Target-native files are copied into that target's generated output using the target's natural config root. For example, with Pi user scope:

targets/pi/extensions/my-plugin-hooks.ts
  -> ~/.pi/agent/extensions/my-plugin-hooks.ts

With Pi project scope, the same source file writes to .pi/extensions/my-plugin-hooks.ts.

If a target-native file has the same output path as generated converter output, the target-native file wins over the generated file and the conversion report records the override. Existing target-specific write behavior still applies when writing to disk; for example, Codex config.toml and hooks.json outputs are merged with existing local config instead of clobbering it. Use target-native files for target-specific glue such as custom Pi TypeScript extensions; prefer generated output for ordinary skills, commands, MCP config, and hooks.

Conversion Config Fields

Field	Type	Default	Description
enabled	bool	true	Enable/disable conversion
targets	list	(required)	Target tools: codex, cursor, opencode, pi
scope	string	"project"	"user" (home dir) or "project" (cwd). Codex Agent Skills are discovered from .codex/skills; MCP/hooks may need user-scope output or manual merge into CODEX_HOME depending on runtime trust/config loading.
output_dir	string	(auto)	Custom output directory. Relative paths resolve from config file location
commands_as_skills	bool	false	Convert commands to skills instead of prompts (Codex-specific)

Component Mapping

How each plugin component maps to target tools:

Component	Codex	Cursor	OpenCode	Pi
Skills	.codex/skills/*/SKILL.md	.cursor/skills/*/SKILL.md	.opencode/skills/*/SKILL.md	.pi/skills/*/SKILL.md or .pi/agent/skills/*/SKILL.md
Commands	Prompts or skills	Commands	Prompts	Prompt templates
Hooks	.codex/hooks.json + features.codex_hooks for supported command hooks	Hooks config	Unsupported	TypeScript extension emulation
MCP servers	.codex/config.toml [mcp_servers.*]	.cursor/mcp.json	opencode.json	Unsupported
LSP servers	Unsupported	Unsupported	opencode.lsp.json	Unsupported
Agents	Unsupported	Unsupported	Unsupported	Unsupported

Mapping fidelity levels:

• Native — direct 1:1 equivalent exists
• Transform — config/schema conversion required
• Emulate — wrapped via a fallback mechanism
• Fallback — degraded to prompt or plain text
• Unsupported — no equivalent in the target

Options Reference

ai-config convert PLUGIN_PATH [OPTIONS]

Option	Description
-t, --target TARGET	Target tool(s): codex, cursor, opencode, pi, all (default: all)
-o, --output DIR	Output directory (default: based on --scope)
--scope SCOPE	user or project — controls default output path
--dry-run	Preview changes without writing files
--best-effort	Continue even if some components fail to convert
--format FORMAT	Console output: summary (default), markdown, json
--report PATH	Write conversion report to a file
--report-format FORMAT	Report file format: json (default) or markdown
--commands-as-skills	Convert commands to skills instead of prompts (Codex)

Multiple targets can be specified:

ai-config convert ./my-plugin -t codex -t cursor

Validating Output

After conversion, use doctor to validate the output:

ai-config doctor --target codex ./output-dir
ai-config doctor --target all ./output-dir

This checks that the converted files have valid structure, required fields, and correct naming conventions for each target tool.

Conversion Cache

Sync-driven conversion uses content hashing to skip re-conversion when plugin sources haven't changed.

--force does a full rebuild (clears plugin cache + re-converts everything):

ai-config sync --force

--force-convert re-converts without clearing the plugin cache (useful after adding a new target or updating the converter):

ai-config sync --force-convert

Examples

Convert a local plugin to Codex

ai-config convert ./my-plugin --target codex --scope project

Creates .codex/skills/ for Codex Agent Skills and .codex/config.toml / .codex/hooks.json when MCP servers or supported hooks are present. The project-scope .codex/ files are validated fragments; for active Codex MCP/hook behavior, merge them into the active CODEX_HOME or run with an explicit CODEX_HOME that points at the generated config.

Convert to all targets with a report

ai-config convert ./my-plugin --report ./report.json

Converts to all targets and writes a JSON report with component mappings and diagnostics.

Dry run with detailed output

ai-config convert ./my-plugin --dry-run --format markdown

Shows what would be created in Markdown format without writing any files.