How to Sync Your AI Coding Setup Across Cursor, Claude Code, and Copilot — So Switching Tools Doesn't Lose Your Project Context

Here's a scenario every developer using AI coding tools eventually hits: your Cursor subscription resets on the 20th, it's the 18th, and you've burned through this month's fast requests. You switch to Claude Code or fire up GitHub Copilot — only to discover that two months of careful .cursorrules tuning, three MCP servers you rely on, and all your project-specific instructions are completely absent. The new tool has no idea what your codebase does, what conventions you follow, or how your deployment works. You are effectively starting from scratch — and you'll have to do it again the next time you switch.

This is the sync AI coding setup problem, and it affects most developers who use more than one AI coding agent. It is not a bug in any particular tool — it is a structural consequence of a young ecosystem where every vendor made independent decisions about where to store configuration, what format to use, and what features to support. The good news is that the community has built practical solutions: a tool-agnostic file format (AGENTS.md), a symlink-based sync CLI (skills-sync), and a chezmoi-based canonical MCP manifest that generates every tool's native config format automatically. This guide walks through all three, with the specific commands and file structures you need to set them up today.

Why Every AI Coding Tool Stores Configuration Differently

Quick Answer: Cursor, Claude Code, and Copilot each invented their own configuration formats before any cross-tool standard existed. The result is four different file paths, three different JSON schemas, and two different concepts of what a "skill" even is — all describing the same underlying information.

The four config locations you need to know

The configuration landscape for the four most popular AI coding agents currently looks like this:

Tool	Instructions / Rules File	MCP Config File
Claude Code	CLAUDE.md (project root)	.mcp.json (project) / ~/.claude.json (user)
Cursor	.cursor/rules/ + .claude/skills/	~/.cursor/mcp.json / .cursor/mcp.json
GitHub Copilot (VS Code)	AGENTS.md (project root)	.vscode/mcp.json
OpenAI Codex	AGENTS.md (project root)	~/.codex/config.toml

Beyond paths and filenames, each tool also has slightly different expectations about content. Claude Code's CLAUDE.md supports embedded shell commands and referenced sub-files. Cursor's rules system understands glob patterns for scoping instructions to specific directories. Copilot's AGENTS.md support is agnostic — it reads plain Markdown headings as semantic hints without enforcing any particular structure. These aren't just file-naming conventions; they represent genuinely different philosophies about what an AI agent's persistent context should look like.

Why this matters when you switch tools mid-project

The practical consequence hits hard the moment you actually need to swap tools. A developer writing about this experience on DEV Community described the cost precisely: after months of careful tuning — TypeScript strictness settings, deployment procedures, database migration conventions — switching from Cursor to GitHub Copilot meant the entire session started cold. Every convention had to be re-explained. And here's the part that stings most: it wasn't even a permanent switch. Cursor's monthly token limit had simply run out, and they needed to keep shipping. Days later, back in Cursor, their carefully maintained .cursorrules file was right where they left it — but everything they'd explained to Copilot was gone.

"The whole ecosystem feels like it's one pricing change away from forcing a migration nobody's config is ready for." — Developer forum discussion on AI tool portability

The Tool-Agnostic AGENTS.md Approach: One File All Tools Can Read

Quick Answer: AGENTS.md is an open Markdown file you place at your project root that acts as a shared briefing document for every AI coding agent that opens your repository. Cursor, Copilot, Codex, and Windsurf read it natively. Claude Code reads CLAUDE.md natively but can treat AGENTS.md as supplementary context.

What to put in your AGENTS.md

AGENTS.md emerged in mid-2025 from a collaboration between Sourcegraph, OpenAI, Google, Cursor, and others, and is now maintained by the Agentic AI Foundation under the Linux Foundation umbrella. Over 60,000 open-source repositories already use it. The format is deliberately minimal — plain Markdown with headings as semantic hints — so that any tool can parse it without needing to know the spec. A well-written AGENTS.md covers four areas:

# AGENTS.md

## Project Overview
This is a Next.js 15 SaaS application using Supabase for auth and Postgres.
Primary language: TypeScript (strict mode enabled).
Package manager: pnpm. Never use npm or yarn.

## Architecture
- /app — Next.js App Router pages
- /lib — Shared utilities and Supabase client
- /components — Reusable UI (Tailwind CSS)
- /supabase/migrations — Database migration files (never edit manually)

## Testing
Run tests with: pnpm test
All new features require a test in /tests/unit/
Integration tests live in /tests/integration/ and require a running Supabase instance.

## Conventions
- Never use `any` in TypeScript
- Use Zod for all runtime validation
- Database changes go through Supabase migrations, never direct SQL
- Commit messages follow Conventional Commits (feat:, fix:, chore:)

## Deployment
- Staging: push to `staging` branch (auto-deploys via Vercel)
- Production: open a PR to `main`, requires one approval

The key discipline is keeping AGENTS.md factual and structural — it should describe what is true about your project, not how to behave. Instructions like "always write concise code" belong in your skills files, not here. AGENTS.md is a README for agents, and like any good README, it loses its value the moment it starts describing personality rather than architecture.

The Claude Code exception — and how to handle it

Claude Code reads CLAUDE.md natively and, as of Marchются 2026, does not auto-load AGENTS.md — though this is an active feature request in the community. The practical workaround is a two-file strategy: maintain AGENTS.md as your cross-tool foundation, and maintain a CLAUDE.md that imports it by reference and adds Claude-specific context on top. Your CLAUDE.md becomes a thin wrapper:

# CLAUDE.md

See AGENTS.md for full project context. The following is Claude-specific.

## Preferred Response Style
- Be concise. No preamble. Show the diff, then explain.
- When refactoring, output only the changed file unless asked otherwise.

## Skills
@.claude/skills/deploy.md
@.claude/skills/migrate-db.md

This keeps the shared context in one place while giving Claude the extra signal it needs. When you update your architecture in AGENTS.md, both Claude and every other tool pick up the change automatically. You are only ever editing one file for the canonical facts about your project, even if you maintain two files for tool-specific behaviour. For more on managing Claude Code specifically, see our guide on how to stop AI agents from breaking your codebase.

Using Symlinks to Keep a Single Source of Truth: The skills-sync Pattern

Quick Answer: skills-sync is a CLI tool that stores all your AI agent skills and configuration in a single workspace, then uses symlinks to make every tool point to the same underlying files. One update propagates everywhere — no manual copying, no drift.

How skills-sync works under the hood

The skills-sync CLI, built by the developer community after the proliferation of incompatible config formats, takes a pragmatic approach: rather than inventing yet another abstraction layer, it simply establishes a canonical workspace directory and creates symlinks (lightweight file-system shortcuts that point to the canonical file rather than copying it) from each tool's expected config location to that shared directory. When you update a skill in the workspace, every tool's symlink automatically reflects the change — because they're all reading the same file.

Setting it up takes four commands:

# Install skills-sync
npm install -g skills-sync

# Initialize a workspace (creates ~/.skills-sync/ by default)
skills-sync init --seed

# Select a profile (useful for work vs personal machines)
skills-sync use personal

# Materialize symlinks into all supported agents
skills-sync sync

After running skills-sync sync, your .claude/skills/, .cursor/rules/, and Copilot's equivalent directories all point to files living under ~/.skills-sync/workspace/. The supported agent list as of early 2026 includes Cursor, Claude Code, GitHub Copilot, OpenAI Codex, and Google Gemini CLI.

The drift check: catching divergence before it accumulates

One of the most underused features of skills-sync is the drift check. Running skills-sync agents drift --dry-run compares what each tool currently has against the canonical workspace state and reports any files that have been modified outside the sync system — which usually means someone edited a config directly in the tool's native location rather than in the workspace. Catching this early matters; configuration drift is easiest to fix before it becomes a discrepancy you've been unknowingly working around for a month.

# Check for drift without making changes
skills-sync agents drift --dry-run

# Example output:
# [cursor] .cursor/rules/typescript.md — IN SYNC
# [claude] .claude/skills/deploy.md — MODIFIED (out of sync)
# [copilot] AGENTS.md — NOT FOUND (agent not configured)

# Apply workspace state to all agents
skills-sync sync

One gotcha worth knowing: skills-sync handles agent-specific features gracefully — for instance, Claude Code's skills support embedded shell scripts while Copilot doesn't — but it does this by emitting warnings rather than failures. Fields that a target agent doesn't support are silently dropped. This means a skill that runs perfectly in Claude Code may behave slightly differently in Copilot, not because the sync failed, but because Copilot executed a stripped-down version. Test your critical skills in every agent at least once, rather than assuming full behavioural parity.

How to Sync MCP Server Configurations Across All Agents

Quick Answer: MCP (Model Context Protocol) servers require separate configuration in every tool. The cleanest fix is a single canonical servers.yaml file managed by chezmoi, which generates each tool's native config format automatically on any machine you set up.

The canonical servers.yaml approach

All four major AI coding tools model MCP (Model Context Protocol — the open standard that lets agents connect to external tools like databases, browsers, and file systems) servers with the same conceptual fields: server name, transport type (stdio for local processes, HTTP/SSE for remote), command, arguments, and environment variables. The only differences are file location and schema shape. This means you can maintain one canonical source and generate all four target files from it.

The recommended approach, as documented in detail by developer Dónal Weldon on DEV Community, uses chezmoi (a dotfile manager that supports templating) with the following layout:

~/.local/share/chezmoi/
├── .chezmoitemplates/
│   └── mcp/               # Reusable template snippets
├── dot_config/
│   └── mcp/
│       └── servers.yaml   # Canonical MCP server list
├── dot_codex/
│   └── config.toml.tmpl   # Generated for OpenAI Codex
├── dot_claude/
│   └── mcp_servers.json.tmpl  # Generated for Claude Code
├── dot_cursor/
│   └── mcp.json.tmpl      # Generated for Cursor
└── dot_vscode/
    └── mcp.json.tmpl      # Generated for VS Code/Copilot

Your canonical servers.yaml might look like this:

servers:
  - name: context7
    transport: stdio
    command: npx
    args: ["-y", "@upstash/context7-mcp"]

  - name: playwright
    transport: stdio
    command: npx
    args: ["-y", "@playwright/mcp@latest"]

  - name: supabase
    transport: stdio
    command: npx
    args: ["-y", "@supabase/mcp-server-supabase@latest"]
    env:
      SUPABASE_ACCESS_TOKEN: "{{ .supabaseToken }}"

Running chezmoi apply renders each .tmpl file into its target location. Adding a new MCP server means editing servers.yaml once and running chezmoi apply once. All four tool configs update in seconds.

Handling secrets safely in multi-tool MCP configs

MCP configurations often include API tokens, database credentials, and other secrets — and the temptation is to hardcode them for convenience. Don't. The chezmoi approach handles secrets correctly by using the private_ and encrypted_ attributes for files containing token fields. This keeps secrets out of your dotfiles repository (which may be public) while still allowing them to be injected into each tool's config at apply time. For a deeper look at what MCP servers you should actually be running — and the security implications of granting them filesystem access — see our overview of how AI coding tools actually work — including the security model for external tool access.

"One canonical MCP model, many generated vendor configs." — The chezmoi multi-tool approach, as described by developer Dónal Weldon on DEV Community

Migrating When a Tool Deprecates Its Config Format

Quick Answer: Config format deprecations happen when tools evolve their agent models. Cursor's move away from .cursorrules is the most prominent recent example. The migration is usually mechanical — a content copy with minor structural changes — and takes 10–30 minutes if your content is already well-organized.

The .cursorrules deprecation: what actually changed

Cursor's v2.4 changelog introduced agent skills and encouraged users to migrate procedural instructions out of .cursorrules and into the .claude/skills/ directory. This wasn't a hard deprecation — .cursorrules still works — but the reasoning behind it is important to understand. The changelog positioned skills as "better for dynamic context discovery and procedural how-to instructions" compared to always-on, declarative rules. In practice this means: your "always apply TypeScript strict mode" rule stays in .cursor/rules/, while "here is how to write a new database migration" becomes a skill file in .claude/skills/ that Cursor discovers on demand.

The key insight for multi-tool developers: .claude/skills/ is shared with Claude Code. Cursor's decision to store its skills in the same directory that Claude Code uses for its own skills was not accidental — it is precisely what makes skills-sync possible. Both tools look in the same place, which means a skill written for Claude Code works in Cursor with no additional setup.

Migrating .cursorrules to CLAUDE.md: a practical walkthrough

If you are starting the multi-tool sync journey from a .cursorrules file, the migration to a portable format looks like this:

# Step 1: Sort your .cursorrules content into two buckets
# Bucket A: Declarative conventions (always-on) → .cursor/rules/ + AGENTS.md
# Bucket B: Procedural how-tos (on-demand) → .claude/skills/ (one file per topic)

# Step 2: Create AGENTS.md with the architectural facts from Bucket A
# (project overview, tech stack, file structure, testing requirements)

# Step 3: Create .cursor/rules/conventions.mdc with the style rules from Bucket A
# (TypeScript settings, naming conventions, formatting preferences)

# Step 4: Create individual skill files in .claude/skills/ from Bucket B
# Example: .claude/skills/database-migrations.md
# Example: .claude/skills/deployment.md

# Step 5: Create CLAUDE.md as a thin wrapper
echo "See AGENTS.md for project context.\n@.claude/skills/database-migrations.md\n@.claude/skills/deployment.md" > CLAUDE.md

# Step 6: Run skills-sync to confirm all agents see the new structure
skills-sync agents drift --dry-run

The total time for this migration on a well-maintained .cursorrules file is typically under 30 minutes. If your file has grown into a 200-line wall of mixed conventions and procedures, the migration will take longer — but that reorganization is worth doing regardless of tool portability, because a badly organized context file gives every AI agent worse output. For more on how Cursor handles its configuration in depth, including the full rules system, our complete Cursor guide covers the details. If you are also setting up GitHub Copilot on a new machine, our GitHub Copilot deep review covers its AGENTS.md support and VS Code MCP discovery settings. And if you're evaluating which tool to invest most heavily in, the head-to-head Cursor vs Copilot vs Codeium comparison is the right starting point.

Sync Strategy Comparison: Which Approach Fits Your Setup?

Quick Answer: The right sync strategy depends on how many tools you use, whether you manage multiple machines, and how much time you want to invest in setup. The three approaches — AGENTS.md only, skills-sync, and chezmoi templates — are complementary, not mutually exclusive.

Strategy	Best For	Setup Time
AGENTS.md + CLAUDE.md only	Single machine, 2–3 tools, project-specific context	15–30 min per project
skills-sync CLI	Developers who maintain many skills files and want automatic propagation across tools	1–2 hours (initial), seconds per update
chezmoi templates	Multi-machine setups; developers who need MCP configs and secrets managed consistently across work and personal environments	2–4 hours (initial), fully automated thereafter
All three combined	Power users who switch tools frequently and need zero-effort portability	Half a day (initial), fully automated thereafter

For most developers, the pragmatic starting point is: write AGENTS.md today (zero tooling required), add skills-sync if you find yourself maintaining more than five skill files across multiple tools, and add chezmoi only if you manage multiple machines or need to handle MCP secrets properly. Doing all three at once is worth it if portability is a genuine daily concern — but doing AGENTS.md alone removes 80% of the pain with 10% of the effort. You can always layer in more automation later. To understand the underlying tools better, our in-depth guide to how AI coding tools actually work covers the context window and agent architecture that makes all of this configuration matter in the first place.

Frequently Asked Questions

How do I share AI coding rules between Cursor, Claude Code, and Copilot?

The most reliable approach is to maintain an AGENTS.md file at your project root — Cursor, GitHub Copilot, and OpenAI Codex all read it automatically. For Claude Code, you also maintain a CLAUDE.md file that contains Claude-specific additions. Tools like skills-sync and chezmoi can automate keeping all four config files in sync from a single canonical source.

What is an AGENTS.md file and which tools support it?

AGENTS.md is an open, tool-agnostic Markdown file placed at your project root that gives AI coding agents persistent context about your project — architecture decisions, coding conventions, testing requirements, and more. As of early 2026, it is natively supported by Cursor, GitHub Copilot (via VS Code), OpenAI Codex, Windsurf, and Kilo Code. Claude Code uses CLAUDE.md instead, though it can be configured to read AGENTS.md as an additional context file.

How do I install the same MCP server across multiple AI coding tools?

Each tool stores MCP configuration at a different path: Claude Code uses ~/.claude.json (user scope) or .mcp.json (project scope), Cursor uses ~/.cursor/mcp.json, and VS Code/Copilot uses .vscode/mcp.json. You can maintain one canonical servers.yaml and use a templating tool like chezmoi to generate all four formats automatically, or use skills-sync which handles this propagation for you.

What is skills-sync and how does it keep agent configurations in sync?

skills-sync is an open-source CLI tool that keeps AI agent skills and MCP configurations synchronized across Cursor, Claude Code, GitHub Copilot, OpenAI Codex, and Google Gemini. It works by storing all configuration in a single workspace and using symlinks so every tool points to the same underlying files rather than maintaining separate copies. When you update a skill or add an MCP server, running skills-sync sync propagates the change to all connected tools instantly.

Why did Cursor deprecate .cursorrules in favor of agent skills?

Cursor deprecated .cursorrules because declarative always-on rules work well for conventions (like "use TypeScript strict mode") but are inefficient for procedural knowledge (like "here is how to deploy to AWS"). Agent skills solve this by letting the model decide when to activate specific knowledge, rather than stuffing every instruction into a single always-on context block. The result is better token efficiency and more targeted agent behaviour.

How do I migrate my .cursorrules to Claude Code's CLAUDE.md format?

The migration is mostly mechanical: sort your .cursorrules content into "declarative conventions" (go into AGENTS.md and .cursor/rules/) and "procedural how-tos" (go into individual .claude/skills/ files), then create a CLAUDE.md that references AGENTS.md and the skills files. The whole process takes under 30 minutes for a well-organized .cursorrules file.

Can I use the same MCP configuration for Cursor and Claude Code?

Yes — the underlying MCP server definitions are identical across tools. The only difference is file location and schema shape. You can maintain one canonical list and auto-generate both ~/.cursor/mcp.json and .mcp.json for Claude Code from it. VS Code/Copilot can also auto-import from Claude Desktop's config if you enable chat.mcp.discovery.enabled in VS Code settings.

What happens to my project context when I switch from Cursor to Claude Code?

Without a portable configuration strategy, you lose everything — coding conventions, architecture decisions, tool preferences, and custom instructions. The fix is to write your project context into AGENTS.md (for cross-tool use) and CLAUDE.md (for Claude-specific context) before you ever need to switch. If you already have .cursorrules, migrating takes about 30 minutes. From then on, any new tool picks up your context immediately.

aicourses.com Verdict

The multi-tool AI coding problem is real, and the community's response has been genuinely useful. AGENTS.md solves the most painful 80% of the problem — shared project context — with zero tooling and a 15-minute time investment. skills-sync and chezmoi solve the remaining 20% (skills propagation and MCP sync) for developers who actually switch tools frequently enough to feel the pain. The ecosystem is clearly converging on AGENTS.md as the cross-tool standard for persistent project context, with tool-specific files like CLAUDE.md and .cursor/rules/ handling the edges that require native features. That convergence is good news: the investment you make in a portable AGENTS.md today will only become more valuable as more tools adopt the standard.

Practically speaking: start with AGENTS.md in every project you work in, even if you only use one tool right now. Treat it like a README for your future self after a two-week vacation — clear, factual, and specific enough that a new agent can start being useful in five minutes. If you run more than two MCP servers, set up the chezmoi canonical manifest immediately rather than letting drift accumulate. And if you hit Cursor's token limit mid-sprint and need to switch to Claude Code or Copilot without losing half a day's context — which is exactly when you'll be most grateful this is already sorted — your AGENTS.md will be waiting. Tool availability and MCP configuration options verified as of March 2026.

From cross-tool context sharing, the natural next question is: which MCP servers are actually worth installing in the first place? Not all of them are reliable, and several popular ones in the registry are effectively abandoned. Our guide to AI coding security risks covers what granting MCP servers filesystem access means in practice — and which risks are worth taking seriously.

Want to learn more about AI? Download our aicourses.com app through this link and claim your free trial!