Skip to main content
command CX Codex

migration — Claude Code command: consolidate AI configs into AGENTS.md

migration moves CLAUDE.md, .cursorrules and the rest of your AI config files into one AGENTS.md, then links each tool's expected filename to it.

MIT ★ 763 updated 2026-03-31

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/migration.md
Open on GitHub

What migration does

The command lists the AI config files present in the repo: CLAUDE.md, .clinerules, .cursorrules, .windsurfrules, .replit.md, .github/copilot-instructions.md, GEMINI.md, AGENT.md. Then it compares their size and content. A single file gets renamed to AGENTS.md. Identical copies keep one primary file and turn into symlinks pointing at it.

Links cover every tool's filename, the older AGENT.md included. GitHub Copilot needs a .github directory with a ../AGENTS.md link inside; Firebase Studio reads .idx/airules.md. You get ls -la output, a git status and a nudge to check the .bak files before deleting them. When directory structure is wanted, /agents-md:init is the suggested follow-up.

Differing configs are the interesting case. The command prints sizes and contents, then asks which route to take: auto-merge, .bak backups, a selective transfer or a guided manual merge. Its toolset is limited to mv, ln, ls, test, grep, echo and Read, so the work is moving and linking files rather than rewriting them. Read those backups yourself before removing them, or a chunk of instructions goes with them.

What it helps with

  • collapse several assistants' config files into a single AGENTS.md
  • drop duplicate CLAUDE.md and .cursorrules files
  • set up symlinks for Cursor, Cline and GitHub Copilot
  • keep .bak copies of conflicting configs before merging
  • audit which AI config files already sit in the repo

Example prompts for the agent

  • Convert this project's configs to AGENTS.md and add symlinks for Cursor and Copilot.
  • Show me which AI config files exist in the repo and how their content differs.
  • Back up .cursorrules and .github/copilot-instructions.md, then build a shared AGENTS.md.

How to install migration

Manually: put the files in place

.claude/commands/migration.md

Call it with /migration. For all projects use ~/.claude/commands/

Questions about migration

How do I install migration in Claude Code?

Place the command file at .claude/commands/migration.md in your project. It is then available as /migration.

What does migration do?

It merges scattered AI config files into one AGENTS.md and points each tool's expected filename at it with a symlink.

What happens when the config files differ?

You see each file's size and content, then choose between auto-merge, .bak backups, a selective transfer or a step-by-step manual merge.

Source text

migration.md · MIT
---
description: Migrate AI assistant configuration to AGENTS.md standard with universal compatibility
category: claude-setup
allowed-tools: Bash(mv:*), Bash(ln:*), Bash(ls:*), Bash(test:*), Bash(grep:*), Bash(echo:*), Read
---

# Convert to Universal AGENTS.md Format

This command helps you adopt the AGENTS.md standard by converting your existing CLAUDE.md file and creating symlinks for compatibility with various AI assistants.

## Current Project State
!`ls -la CLAUDE.md AGENTS.md AGENT.md GEMINI.md .cursorrules .clinerules .windsurfrules .replit.md .github/copilot-instructions.md 2>/dev/null | grep -E "(CLAUDE|AGENT|AGENTS|GEMINI|cursor|cline|windsurf|replit|copilot)" || echo "Checking for AI configuration files..."`

## Task

Convert this project to use the AGENTS.md standard following these steps:

### 1. Pre-flight Checks
Check for existing AI configuration files:
- CLAUDE.md (Claude Code)
- .clinerules (Cline)
- .cursorrules (Cursor)
- .windsurfrules (Windsurf)
- .replit.md (Replit)
- .github/copilot-instructions.md (GitHub Copilot)
- GEMINI.md (Gemini CLI)
- AGENTS.md (if already exists)
- AGENT.md (legacy, to be symlinked)

### 2. Analyze Existing Files
Check all AI config files and their content to determine migration strategy:

**Priority order for analysis:**
1. CLAUDE.md (Claude Code)
2. .clinerules (Cline)
3. .cursorrules (Cursor)
4. .windsurfrules (Windsurf)
5. .github/copilot-instructions.md (GitHub Copilot)
6. .replit.md (Replit)
7. GEMINI.md (Gemini CLI)

**Content Analysis:**
- Compare file sizes and content
- Identify identical files (can be safely symlinked)
- Detect different content (needs merging or user decision)

### 3. Perform Smart Migration

**Scenario A: Single file found**
```bash
# Simple case - move to AGENTS.md
mv CLAUDE.md AGENTS.md  # or whichever file exists
```

**Scenario B: Multiple identical files**
```bash
# Keep the priority file, symlink others
mv CLAUDE.md AGENTS.md
ln -sf AGENTS.md .cursorrules  # if .cursorrules was identical
```

**Scenario C: Multiple files with different content**
1. **Automatic merging** (when possible):
   - Different sections can be combined
   - No conflicting information
   - Clear structure boundaries

2. **User guidance** (when conflicts exist):
   - Show content differences
   - Provide merge recommendations
   - Offer options:
     - Keep primary file, backup others
     - Manual merge with assistance
     - Selective migration

### 4. Handle Conflicts Intelligently

**When conflicts detected:**
1. **Display differences:**
   ```
   ⚠️  Multiple AI config files with different content found:
   
   📄 CLAUDE.md (1,234 bytes)
   - Build commands: npm run build
   - Testing: vitest
   
   📄 .cursorrules (856 bytes)  
   - Code style: Prettier + ESLint
   - TypeScript: strict mode
   
   📄 .github/copilot-instructions.md (567 bytes)
   - Security guidelines
   - No secrets in code
   ```

2. **Provide merge options:**
   ```
   Choose migration approach:
   1. 🔄 Auto-merge (recommended) - Combine all unique content
   2. 📋 Keep CLAUDE.md, backup others (.cursorrules.bak, copilot-instructions.md.bak)
   3. 🎯 Selective - Choose which sections to include
   4. 🛠️  Manual - Guide me through merging step-by-step
   ```

3. **Execute chosen strategy:**
   - **Auto-merge**: Combine sections intelligently
   - **Backup**: Keep primary, rename others with .bak extension
   - **Selective**: Interactive selection of content blocks
   - **Manual**: Step-by-step merge assistance

### 5. Create AGENTS.md and Symlinks
After handling content merging, create the final structure:
```bash
# Claude Code
ln -s AGENTS.md CLAUDE.md

# Cline
ln -s AGENTS.md .clinerules

# Cursor
ln -s AGENTS.md .cursorrules

# Windsurf
ln -s AGENTS.md .windsurfrules

# Replit
ln -s AGENTS.md .replit.md

# Gemini CLI, OpenAI Codex, OpenCode
ln -s AGENTS.md GEMINI.md

# Legacy AGENT.md symlink for backward compatibility
ln -s AGENTS.md AGENT.md

# GitHub Copilot (special case - needs directory)
mkdir -p .github
ln -s ../AGENTS.md .github/copilot-instructions.md

# Firebase Studio (special case - needs .idx directory)
mkdir -p .idx
ln -s ../AGENTS.md .idx/airules.md
```

### 6. Verify Results
- Use `ls -la` to show all created symlinks
- Display which AI assistants are now configured
- Show any backup files created (.bak extensions)
- Confirm that AGENTS.md includes the symlink documentation note
- Verify content completeness (all important sections included)

### 7. Git Guidance
If in a git repository:
- Show git status (including new AGENTS.md and any .bak files)
- Suggest adding AGENTS.md and symlinks to git
- Recommend reviewing .bak files before deleting them
- Remind to update .gitignore if needed (some teams ignore certain config files)

### 8. Post-Migration Cleanup
After successful migration and git commit:
1. **Review backup files** (.bak extensions) to ensure nothing important was missed
2. **Delete backup files** once satisfied with AGENTS.md content
3. **Test with different AI assistants** to ensure all symlinks work correctly
4. **Run `/agents-md:init`** if you want to add directory structure and latest best practices

## Why AGENTS.md?

AGENTS.md is becoming the standard for AI assistant configuration because:
- Single source of truth for all AI tools
- No more duplicating content across multiple files
- Consistent experience across Claude Code, Cursor, Windsurf, and other tools
- Future-proof as new AI tools emerge

AGENTS.md emerged from collaborative efforts across the AI software development ecosystem, including OpenAI Codex, Amp, Jules from Google, Cursor, and Factory.

Learn more at https://agents.md

© carlrannaberg · MIT · carlrannaberg/claudekit

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →
bringyour-migration-auditor 8bitconcepts bringyour-migration-auditor runs a read-only check on a project that just moved from Claude to Claude: rule files, hooks, MCP config, skills, secret references. Use it before the agent edits code. CX Codex ★ 1,596repo stars claude-migrate-memory-to-doc daymade The claude-migrate-memory-to-doc skill exports Claude Code's private per-project memory into tool-agnostic documents so Codex, Cursor, and other AI editors read the same user profile and preferences. CX Codex +1 388installs assess-react-native-migration callstackincubator assess-react-native-migration audits product repositories and decides whether a mobile app should move to React Native, before anyone writes migration code. CX Codex +1 2,700installs mapbox-google-maps-migration mapbox mapbox-google-maps-migration — a Claude Code skill that walks an agent through migrating from Google Maps Platform to Mapbox GL JS. It covers API equivalents, pattern rewrites, and the declarative model Mapbox uses. CX Codex +1 1,500installs kotlin-tooling-immutable-collections-0-5-x-migration JetBrains kotlin-tooling-immutable-collections-0-5-x-migration is a Claude Code skill that migrates Kotlin and Java code from kotlinx.collections.immutable 0.3.x and 0.4.x to 0.5.x, renaming calls flagged by the compiler. CX Codex +1 1,300installs ionic-enterprise-sdk-migration capawesome-team ionic-enterprise-sdk-migration walks the agent through moving a Capacitor app off discontinued Ionic Enterprise SDK plugins onto Capawesome replacements: OAuth, Vault, Biometrics, Secure Preferences, SQLite. CX Codex +1 1,200installs

From the same set54

The whole set →
create-command The create-command command builds a Claude Code slash command from your requirements, then shows its file location and how to invoke it. CX Codex +1 ★ 763repo stars commit Builds a git commit that matches your project's conventions: scans the diff, updates docs, writes the message. CX Codex +1 ★ 763repo stars code-search code-search searches the codebase for matching files, functions, and patterns, returning a clean list of paths. Handy for locating relevant code quickly without full explanations. CX Codex ★ 763repo stars validate-and-fix validate-and-fix is a Claude Code command that runs project checks and assigns independent fixes to parallel agents. It discovers build, test, and lint commands in project instructions and package.json. CX Codex +1 ★ 763repo stars research-expert research-expert gathers web information in parallel, adapts depth across three distinct modes, and outputs full reports to files to avoid token bloat. CX Codex ★ 763repo stars create-subagent create-subagent builds a domain-focused subagent with defined tasks, tools, boundaries, and project context checks. Use it when a one-off command is too narrow. CX Codex +1 ★ 763repo stars research research fans a question out to parallel subagents, reads their saved reports from /tmp, and merges the lot into one cited file. CX Codex +1 ★ 763repo stars cleanup cleanup finds disposable debug scripts, test files, and generated reports from Claude Code sessions and prompts before removing them. CX Codex +1 ★ 763repo stars

Project sponsors

Companies that keep this analytics open