Switch between AI coding tools — Cursor, Claude Code, Codex, and more — without losing your setup. One CLI command carries your agents, skills, rules, and commands across.
A protocol standard that lets developers switch between AI coding tools (Cursor, Claude Code, Codex, etc.) without losing their setup. It works like a migration adapter: the user runs a single CLI command and their agents, skills, rules, and commands are carried across — automatically where possible, with a report where the conversion is approximate.
The protocol does not invent new file formats. It reuses the formats the industry has already converged on (AGENTS.md, SKILL.md) as its canonical intermediate representation, and only defines new schemas where no standard exists yet (subagents, commands).
AI coding tools have divergent configuration ecosystems. Switching tools today means manually re-reading documentation and rebuilding your setup from scratch. The protocol automates the 80% that is portable and clearly flags the 20% that needs human review.
| Tool | Memory / Rules file | Skills | Subagents | Commands |
|---|---|---|---|---|
| Cursor | .cursor/rules/*.mdc (or legacy .cursorrules) | None native | None native | None native |
| Claude Code | CLAUDE.md + .claude/ | .claude/skills/<name>/SKILL.md | .claude/agents/<name>.md | .claude/commands/<name>.md |
| Codex | AGENTS.md | SKILL.md (via agentskills.io) | In development | None native |
The protocol is deliberately not a new standard — it is glue between existing ones.
The Linux Foundation–stewarded open standard for coding agent instructions, read natively by 20+ tools including Cursor, Codex, Copilot, Gemini CLI, Aider, Windsurf, and Zed. It is plain Markdown with no required schema. Claude Code reads CLAUDE.md natively, but the common pattern is to import AGENTS.md from CLAUDE.md so one file serves all tools. The protocol uses AGENTS.md as the canonical rules/memory representation in the hub.
Defines reusable, self-contained skill folders. A skill is a directory containing a SKILL.md with YAML frontmatter (name, description) plus an instructional body. Skills are already highly portable — the protocol copies them nearly verbatim, adjusting only the installation path.
The architecture is a hub with optional pairwise shortcuts, chosen to avoid the O(N²) adapter explosion that a pure peer-to-peer design produces.
Every tool implements two functions:
import — reads the tool's native artifacts and produces the Canonical IR (see §5)
export — reads the Canonical IR and writes the tool's native artifacts
A migration from Tool A to Tool B is: export_B(import_A(source)). This means adding a new tool requires only writing one import + one export, not a new adapter for every existing tool.
Where a hub round-trip loses information that a direct conversion could preserve, a tool can ship an override adapter for a specific target. The migration runner checks for an override before falling back to the hub path.
Example: Cursor's per-rule glob scoping (.mdc frontmatter) has no equivalent in AGENTS.md. A direct cursor → claude_code override could preserve those globs as section comments in CLAUDE.md, which is lossier than ignoring them but better than silence.
Where an artifact cannot be mapped cleanly, the protocol:
1. Makes the best available approximation (never silently drops content)
2. Records the transformation in MIGRATION_REPORT.md with a human-readable description of what changed and what requires manual review
The IR is a directory that a migrated setup passes through:
AGENTS.md and SKILL.md are the standards themselves — no transformation needed in the common case. The protocol's only original schema work is for subagents and commands, which have no cross-tool standard yet.
Records provenance and is the source of truth for MIGRATION_REPORT.md:
<artifact>.map.md is the human-readable spec for how one artifact maps to another (named .map.md to avoid collision with the real AGENTS.md). <artifact>.py is the implementation; it must pass golden fixtures. tool.json is machine-readable; tool.md is human-readable.
Each tool declares its own artifacts, detection signals, and capabilities. This is what the CLI reads to know how to handle a tool — not hardcoded logic.
The capabilities block drives best-effort logic. If the target tool declares per_rule_globs: false, the importer knows to flatten and log the loss.
Not all artifacts migrate equally. The protocol defines four tiers:
| Tier | Artifacts | Typical loss | Strategy |
|---|---|---|---|
| Standard | Rules / memory (AGENTS.md) | Cursor glob scoping flattens; otherwise clean | Hub: import → AGENTS.md → export |
| Portable | Skills (SKILL.md) | Near-zero; path relocation only | Direct copy + path adjustment |
| Tool-specific | Subagents, commands | Tool-specific fields approximated | Hub with normalized IR; override for known pairs |
| Deferred (v2+) | MCP config, hooks | High loss; tool-specific behaviour | Phase 3 |
Phase 1 v1 scope: The first implementation covers only the top three tiers (rules, skills, subagents + commands) for two tools: Cursor → Claude Code (the easy, mostly-lossless direction) and Claude Code → Cursor (the harder reverse, with more best-effort transforms).
When the target directory already contains setup files:
This ensures the migration is always reversible.
These are documented decisions, not omissions:
| Decision | Options Considered | Chosen | Rationale |
|---|---|---|---|
| Core architecture | Direct N×N, Hub, Hybrid | Hybrid hub + direct overrides | O(N) default cost; direct overrides for lossless pairwise cases |
| Lossiness behaviour | Fail, warn+skip, best-effort, stub | Best-effort + report | Maximises migrated value; never silently drops; loss is actionable |
| v1 artifact scope | All / rules+skills / +agents+commands | Rules, skills, subagents, commands | MCP + hooks deferred; covers 90% of day-to-day setup |
| Canonical format | Invent new format, reuse AGENTS.md | Reuse AGENTS.md + SKILL.md as IR | Avoids protocol lock-in; migrated IR is immediately usable without the protocol |
| Spec vs code authority | Code is truth, spec is truth | Spec (.map.md) + golden fixtures | Prevents spec/impl drift |
| Merge policy | Overwrite, fail, merge | Merge-by-default with backup | Reversible; safe for projects with partial existing setup |
| Distribution | npm, pip, standalone | Python (uvx/pipx), language-agnostic adapter interface | Python reference impls; adapters speak JSON so future impls can use any language |
The following require a decision before Phase 1 implementation begins: