Migrate Skill

Convert AI documentation between formats and tools. Each migration type has its own step-by-step procedure.

Step 1: Determine Migration Type

Parse $ARGUMENTS to determine which migration to perform:

Argument	Migration
cursorrules-to-mdc	.cursorrules → .cursor/rules/*.mdc (split into focused files)
monolith-to-modular	Single large CLAUDE.md → .claude/rules/ separate files
any-to-agents-md	Existing Claude/Cursor docs → AGENTS.md for Codex CLI
claude-to-cursor	.claude/rules/*.md → .cursor/rules/*.mdc (convert format)
cursor-to-claude	.cursor/rules/*.mdc → .claude/rules/*.md (convert format)
claude-to-plugin	Extract project docs from CLAUDE.md into plugin structure

If no argument provided, scan for what migrations are available and ask: "I found the following migration opportunities. Which would you like to perform?"

Migration 1: .cursorrules → .cursor/rules/*.mdc

When to use: Legacy flat .cursorrules file exists. Cursor now recommends MDC format for better targeting and discoverability.

Steps:

1. Read .cursorrules file. Verify it exists and has content.

2. Analyze the content to identify distinct topic areas. Look for:

   • Clear section headers or rule groups
   • Different file types being targeted
   • Distinct concerns (coding style, testing, API patterns, etc.)

3. Split into focused files. For each distinct topic:

   • Create a file name: .cursor/rules/[topic].mdc
   • Naming examples: general.mdc, typescript.mdc, testing.mdc, api-patterns.mdc, react-components.mdc

4. For each new MDC file, add frontmatter:

   ---
   description: [Topic-specific description with keywords]
   alwaysApply: [true for general/critical rules, false for topic-specific]
   globs:
     - [relevant file patterns, if topic-specific]
   ---

   alwaysApply decision:

   • true → rules that apply everywhere (naming conventions, critical standards)
   • false with globs → rules for specific file types (React components, test files)
   • false without globs → specialized rules AI discovers by description

5. For globs, use these patterns:

   • TypeScript files: **/*.ts, **/*.tsx
   • Test files: **/*.test.ts, **/*.spec.ts, **/*.test.tsx
   • React components: src/components/**/*.tsx
   • API files: src/api/**/*.ts, src/services/**/*.ts
   • Config files: *.config.ts, *.config.js

6. Preserve all code examples from the original file, placing them in the appropriate new file.

7. After creating all MDC files: archive the original with git mv .cursorrules .cursorrules.bak or ask user if they want to delete it.

8. Report all files created.

---

Migration 2: Monolithic CLAUDE.md → .claude/rules/

When to use: CLAUDE.md contains many distinct rule sections inline and would benefit from modular organization — detail extracted to dedicated rule files with cross-references left in CLAUDE.md.

Steps:

1. Read the full CLAUDE.md. If it already reads as an orientation guide with cross-references rather than exhaustive inline rules, note: "Your CLAUDE.md is already well-structured. Consider keeping it as-is unless specific sections feel unwieldy."

2. Parse the structure. Identify major sections (## headers) and what each covers.

3. Classify each section:

   • Keep in CLAUDE.md: Quick Context, Tech Stack, Package Structure, Key Commands, Core Hooks/Services
   • Extract to rules: Coding standards, Date handling, API patterns, Testing conventions, Error handling, i18n requirements, Color/design rules, specific complex workflows

4. For each section to extract:

   • Create .claude/rules/[topic].md with the section content
   • In CLAUDE.md, replace the extracted section with a one-line reference:

     **See**: `.claude/rules/[topic].md`

   • Add paths: frontmatter to the new rule file if it applies only to specific directories:

     ---
     paths:
       - packages/frontend/src/**
     ---

5. Review the slimmed-down CLAUDE.md. It should now feel like an orientation guide, not a manual — cross-references pointing to rule files rather than inline detail. Each extracted rule file should cover one topic clearly; if a rule file still feels unwieldy, split further by sub-topic.

6. Report all files created and the final CLAUDE.md line count.

---

Migration 3: Any → AGENTS.md (for Codex CLI)

When to use: Project uses Claude Code and/or Cursor but not yet set up for Codex CLI. Need to create AGENTS.md from existing docs.

Steps:

1. Read all existing AI docs:

   • CLAUDE.md (if exists)
   • .claude/rules/*.md (if exist)
   • .cursor/rules/*.mdc (if exist)
   • package.json scripts section

2. Extract essential content for AGENTS.md:

   From CLAUDE.md:

   • Project description → Overview section
   • Key commands → Commands section
   • Package structure → Repository Layout section
   • Critical rules → Coding Standards section

   From rule files:

   • Combine all rules → Coding Standards section (organized by topic)

3. Build AGENTS.md following this structure:

   # [Project Name] — Agent Guide
   
   ## Overview
   [1-2 sentence description from CLAUDE.md or package.json description]
   
   ## Commands
   \`\`\`bash
   [package-manager] run dev      # [description]
   [package-manager] run build    # [description]
   [package-manager] run test     # [description]
   [package-manager] run lint     # [description]
   \`\`\`
   
   ## Repository Layout
   \`\`\`
   [actual directory structure — use `ls` to generate]
   \`\`\`
   
   ## Coding Standards
   ### [Topic from each rule file]
   [Rules in plain language, no XML tags]
   
   ## Testing
   [Test framework, command, and expectations]
   
   ## Critical Rules
   [Top 5-10 most important rules across all Claude/Cursor docs]

4. For monorepos: create AGENTS.md in each package directory as well, scoped to that package's conventions. Keep AGENTS.md files concise — root as a brief overview, package-level scoped to just that package's conventions. Move detailed rules into rule/reference files and cross-reference.

5. Optionally create .codex/config.toml with detected settings:

   [sandbox]
   network = false
   
   [shell]
   default = "bash"
   timeout = 120

---

Migration 4: Claude .md → Cursor .mdc

When to use: Claude rules exist but Cursor is not yet configured. Convert all Claude rules to MDC format.

Steps:

1. Glob all .claude/rules/*.md files. If none exist, report and exit.

2. For each rule file:
   a. Read the file
   b. Extract topic from filename and content
   c. Determine appropriate frontmatter:

   • alwaysApply: true for critical rules, false for topic-specific
   • Add globs based on the rule topic
     d. Convert format:
   • XML tags (<required>, <forbidden>) → bold headers (## ALWAYS, ## NEVER)
   • <preferred> → ## PREFERRED
     e. Write to .cursor/rules/[same-name].mdc

3. If .cursorrules already exists: warn user and ask whether to merge or replace.

4. Report all files created.

---

Migration 5: Cursor .mdc → Claude .md

When to use: Cursor rules exist but Claude Code is not yet configured. Convert MDC rules to Claude format.

Steps:

1. Glob all .cursor/rules/*.mdc files. If none exist, report and exit.

2. For each MDC file:
   a. Read the file
   b. Strip YAML frontmatter
   c. Convert format:

   • Bold **ALWAYS** headers → ## ALWAYS DO
   • Bold **NEVER** headers → ## NEVER DO
   • Preserve all code examples
     d. Write to .claude/rules/[same-name].md

3. If CLAUDE.md exists: ask if the user wants to add cross-references to the new rule files.

4. If no CLAUDE.md: suggest running the generate skill to create one.

---

Migration 6: Claude → Plugin Structure

When to use: A project's CLAUDE.md and rules have evolved to a generic, reusable pattern that should be packaged as a plugin for other projects.

Steps:

1. Read CLAUDE.md and all .claude/rules/*.md files.

2. Identify what is project-specific vs. reusable:

   • Project-specific: project name, actual commands, specific file paths → stays in CLAUDE.md
   • Reusable: design patterns, architectural decisions, universal conventions → goes in plugin

3. Create plugin directory structure:

   .claude/plugins/[plugin-name]/
   ├── .claude-plugin/
   │   └── plugin.json
   ├── skills/
   └── reference/

4. Write plugin.json:

   {
     "name": "[plugin-name]",
     "version": "1.0.0",
     "description": "[what this plugin provides]",
     "author": { "name": "[author]" }
   }

5. For each reusable rule, create a rule file in the plugin's reference/ directory.

6. Report the created structure and suggest publishing to a plugin marketplace.

---

After Any Migration

Progressive disclosure verification — run before reporting:

• CLAUDE.md: reads like an orientation guide with cross-references, not an exhaustive manual (typically 100–200 lines)
• Each rule file: covers one topic clearly; if it covers many distinct topics, suggest splitting (typically 50–200 lines)
• Any alwaysApply MDC body: focused and brief — it loads on every interaction
• AGENTS.md root: concise overview; detailed rules in nested or rule files
• No rule appears verbatim in more than one file — cross-references used instead

Always provide a summary:

## Migration Complete

**Type:** [migration type]
**Files Created:** [n]
**Files Modified:** [n]
**Files Archived/Deleted:** [n]

### Created Files
- [path]: [brief description]

### Next Steps
1. Review the generated files for accuracy
2. Test that AI tools pick up the new docs correctly
3. Commit changes with a descriptive message
4. [Any migration-specific next steps]