Chatgpt Migrator

ChatGPT to Claude Migration Tool

You are running a migration pipeline that turns a user's ChatGPT conversation history into useful Claude artefacts. The export can be enormous (hundreds of megabytes, thousands of conversations), so the process is designed to work within context window limits through a multi-stage pipeline.

This skill is fully self-contained. It walks the user through every step from start to finish, including verifying the output with them and showing them exactly how to import everything into Claude.

Two Migration Paths

Users may arrive via two different routes:

Path 1 (Quick Start): They pasted a prompt into ChatGPT to extract its stored memories, then imported those into Claude via claude.com/import-memory or by manually adding them. This is fast but only captures what ChatGPT explicitly memorised, which is typically a small, biased subset.

Path 2 (Deep Migration): They exported their full ChatGPT data and want you to process it. This is what the rest of this skill handles.

Many users will do Path 1 first and then come to Path 2 later when their data export arrives (it can take up to 24 hours). In this case, they already have Claude memories from Path 1. The interview stage (Question 5) will detect this and the synthesis stage will cross-reference the Path 1 memories with the deep analysis results, enriching rather than duplicating.

Before You Begin

Read the reference files in this skill's directory to understand the batch analysis prompts and output formats:

• references/batch-analysis-prompt.md - The prompt used to analyse each batch
• references/synthesis-prompt.md - The prompt used for final synthesis
• scripts/preprocessor.py - The Python preprocessor that compresses the raw export

Time Estimates

Processing time depends on the size of the export. Share these estimates with the user early and give regular updates throughout:

| Export size | Batches | Estimated time | |---|---|---| | Small (under 200 conversations) | 3-5 batches | 10-15 minutes | | Medium (200-800 conversations) | 8-15 batches | 20-30 minutes | | Large (800-1500 conversations) | 15-25 batches | 30-45 minutes | | Very large (1500+ conversations) | 25-40 batches | 45-60 minutes |

These estimates assume batch analysis is the bottleneck (it is). Preprocessing takes under a minute regardless of size. Synthesis takes 2-5 minutes. The fact-checking interview and import walkthrough add another 5-10 minutes at the end.

After preprocessing, you'll know the exact batch count. Recalculate and share a more precise estimate at that point: roughly 1.5-2 minutes per batch when processing in waves of 3-5.

Progress Tracking (Compaction Resilience)

Large exports can take a long time to process, and sessions may hit context limits mid-run. To handle this, the pipeline maintains a progress.json file in the migration-workspace that tracks exactly where things stand. This is the first file you should check when starting work.

At the very start of every session, look for /migration-workspace/progress.json. If it exists, read it and resume from wherever the pipeline left off. If it doesn't exist, start from Stage 0.

The progress file has this structure:

{
  "current_stage": 3,
  "stage_name": "batch_analysis",
  "export_path": "/path/to/export",
  "skill_path": "/path/to/skill",
  "interview": {
    "scope": "everything",
    "priority": "understand_me",
    "target": "all_platforms",
    "claude_experience": "few_months",
    "claude_memories_provided": true
  },
  "preprocessing": {
    "completed": true,
    "total_batches": 22,
    "batch_files": ["batch-001-deep.json", "batch-002-deep.json", "..."]
  },
  "batch_analysis": {
    "completed_batches": ["batch-001-deep.json", "batch-002-deep.json"],
    "pending_batches": ["batch-003-deep.json", "batch-004-medium.json", "..."],
    "failed_batches": []
  },
  "synthesis": {
    "completed": false,
    "files_produced": []
  },
  "fact_check": {
    "completed": false,
    "facts_presented": [],
    "facts_kept": [],
    "facts_discarded": [],
    "corrections": []
  },
  "last_updated": "2026-03-06T14:30:00Z"
}

Update this file after every meaningful step: after the interview, after preprocessing, after each wave of batch analysis completes, after synthesis, after the fact-check interview. Write it with json.dumps(..., indent=2) so it's human-readable.

When resuming:

• Stage 0-1 complete: Skip straight to preprocessing or batch analysis
• Mid batch analysis: Check which analysis-NNN.json files already exist in the migration-workspace. Any batch with a corresponding analysis file is done. Process only the remaining batches.
• All batches done: Jump to synthesis
• Synthesis done: Jump to fact-checking interview
• Fact-check done: Jump to delivery and import walkthrough

This means the user can hit compaction, start a new session, say "continue the migration", and the skill will pick up right where it left off without re-processing anything or re-asking interview questions.

Stage 0: Check for Existing Progress, Then Identify the Export

First, check if migration-workspace/progress.json exists in the workspace. If it does, read it and skip to whatever stage is indicated. If the user says something like "continue", "keep going", or "pick up where we left off", this is your cue to look for the progress file.

If no progress file exists, look in the user's workspace folder for signs of a ChatGPT export. The telltale files are:

• conversations-000.json, conversations-001.json, etc. (the actual conversation data)
• chat.html (an HTML rendering of all conversations, not needed for processing)
• user.json (basic account info)
• user_settings.json (settings and preferences)
• export_manifest.json (file listing)
• Various UUID-named folders (conversation attachments)

If you find these files, confirm with the user that this is their ChatGPT export and move to Stage 1.

If the export files aren't found

The user might not have their export yet, or they might have selected the wrong folder. Handle this warmly and practically. Use AskUserQuestion to ask:

"I can't see a ChatGPT export in this folder. Where are you in the process?"

• I haven't exported my data yet (show me how)
• I've exported it but it's in a different folder
• I'm waiting for the export email from ChatGPT
• I just want to do the quick migration (no export needed)

If they haven't exported yet, walk them through it step by step:

1. Open ChatGPT (chatgpt.com)
2. Click your profile icon in the top-right corner
3. Go to Settings
4. Click Data controls in the left sidebar
5. Click Export data then Confirm export
6. ChatGPT will email you a download link. This can take anywhere from a few minutes to 24 hours, though it's usually under an hour.
7. When the email arrives, click the download link, download the zip file, and unzip it.
8. Then come back here and either select the unzipped folder, or drop it into your current workspace.

Then offer Path 1 as something they can do right now while they wait: "While you're waiting for the export, you can do the quick migration. This takes 5 minutes and gets your core ChatGPT context into Claude immediately." Explain Path 1 (the ChatGPT memory extraction prompt from the Two Migration Paths section above) and walk them through it.

If they've exported but it's in a different folder, ask them to select the correct folder or tell you the path. If the tool supports directory selection (e.g., Cowork's requestcoworkdirectory), use that.

If they're waiting for the email, offer Path 1 as above. Also let them know they can come back to this conversation (or start a new one) once the export arrives.

If they just want the quick migration, walk them through Path 1 entirely:

1. Give them the ChatGPT memory extraction prompt to paste into ChatGPT
2. Tell them to copy ChatGPT's response
3. Direct them to claude.com/import-memory to paste it, or show them how to add memories manually in Claude's settings
4. Let them know that if they want to do the deep migration later, they can export their data and come back.

The key principle: never leave the user stuck. Every path should lead somewhere useful, even if they don't have their export data yet.

Stage 1: Interview

Before processing anything, have a brief conversation with the user to understand what they want. Use the AskUserQuestion tool for this. Ask about:

Question 1: Scope - "What would you like to extract from your ChatGPT history?"

• Everything (work, personal, creative, all of it)
• Mostly work/professional stuff
• Mostly personal/creative stuff
• A specific topic or project (ask them what)

Question 2: Priority - "What matters most to you in the migration?"

• Having Claude understand who I am (personality, preferences, communication style)
• Carrying over my professional context (projects, expertise, workflows)
• Preserving useful reference material (research, decisions, analysis)
• Getting set up with good system prompts and skills for how I actually use AI

Question 3: Target - "Where will you primarily use Claude?"

• Claude.ai (web/app)
• Cowork (desktop automation)
• Claude Code (developer tool)
• Multiple / all of the above

Question 4: Claude experience - "What's your Claude experience so far?"

• I'm completely new to Claude (just switched from ChatGPT)
• I've been using Claude for a few weeks
• I've been using Claude for a few months
• I've been using Claude for 6+ months

This shapes the tone and depth of the import walkthrough. New users need more guidance on Claude's features, memory, and projects. Experienced users mainly need their ChatGPT context ported over efficiently.

Question 5: Existing Claude memories - "Do you have memories saved in Claude that we should cross-reference with your ChatGPT history?"

• Yes, I have Claude memories (ask them to paste or export their memories)
• No / not sure

If they have existing Claude memories, save them to the migration-workspace as existing-claude-memories.txt. These will be cross-referenced during synthesis to identify confirmed facts, outdated information, and new discoveries.

After the interview, write (or update) progress.json in the migration-workspace with the interview answers and set current_stage to 2. This way, if the session is interrupted, the next session won't re-ask all the questions.

Stage 2: Preprocess

Run the preprocessor script to compress the raw export into manageable batches:

python3 /scripts/preprocessor.py "" "/migration-workspace"

The preprocessor applies recency weighting automatically:

• Conversations are tagged with recency eras (recent/mid/older/historical)
• Recent medium conversations (50-200 words, less than 1 year old) are promoted to deep tier
• Recent light conversations (20-50 words, less than 1 year old) are promoted to medium tier
• All batches are sorted recent-first so Claude sees the most current picture first

This produces:

• 00-overview.json - High-level stats with recency breakdown and separate recent vs all-time keyword analysis
• 01-title-index.json - Every conversation title with date, word count, recency era, and tier
• 02-user-profile.json - Account info from user.json
• batch-NNN-{deep|medium|light}.json - Conversation content in context-window-sized batches, sorted recent-first

Read 00-overview.json first and share the key stats with the user. This helps them understand the scope and sets expectations.

After sharing the stats, give the user a time estimate. Now that you know the exact batch count, calculate: roughly 1.5-2 minutes per batch in waves of 3-5, plus 2-5 minutes for synthesis, plus 5-10 minutes for fact-checking and import walkthrough. Tell the user something like: "You've got 22 batches, so the analysis phase will take roughly 35-45 minutes. I'll give you updates as each wave finishes."

After preprocessing completes, update progress.json: set current_stage to 3, preprocessing.completed to true, and list all batch files. This is critical because preprocessing is deterministic and never needs to be re-run.

Stage 3: Batch Analysis

This is the core processing stage and the longest part of the pipeline. For each batch file, you need to extract structured insights. The batches come in three tiers:

Deep batches (conversations with 200+ user words): Full message content included. These are the richest source of personal context, preferences, and patterns. Process these carefully.

Medium batches (50-200 user words): User messages only. Good for identifying topics, recurring needs, and professional context.

Light batches (under 50 words): Metadata only (title, date, model). Useful for understanding breadth of usage and topic distribution, but not much else.

Processing approach: waves of 3-5 subagents

Use subagents (the Task tool) to process batches in parallel, but limit each wave to 3-5 subagents at a time. This keeps wait times manageable (each wave takes roughly 1.5-2 minutes) and gives the user regular progress updates rather than one long silence.

For each batch, spawn a subagent with the batch analysis prompt from references/batch-analysis-prompt.md, adapted for the batch tier.

The subagent should read the batch file and produce a structured analysis saved to the migration-workspace. Name the output files analysis-NNN.json to match their batch numbers.

Process deep batches first (they take longest and contain the most value), then medium, then light.

Important: Don't try to read the batch files directly into your own context. They're 150-240KB each. Use subagents so each batch gets a fresh context window.

Wave processing loop

1. Launch 3-5 subagents for the next wave of batches
2. Wait for them to complete
3. Update progress.json with the newly completed batches
4. Tell the user: "Wave complete: [X] of [Y] batches done. [brief note on what's emerging]. Next wave starting now, roughly [Z] minutes remaining."
5. Launch the next wave
6. Repeat until all batches are processed

The progress update after each wave is important. Keep it brief but informative: mention a finding or two so the user knows the analysis is substantive, and always include the updated time estimate.

Progress tracking during batch analysis

After each wave of subagents completes, update progress.json: move those batches from pending_batches to completed_batches and update last_updated. This way, if the session hits compaction mid-way through batch analysis, the next session can see exactly which batches are done (it can also verify by checking which analysis-NNN.json files exist on disk).

When resuming mid-batch-analysis: list the analysis-*.json files in the migration-workspace, compare against the full batch list from preprocessing, and only process the missing ones.

Stage 4: Synthesis

Once all batch analyses are complete, update progress.json with current_stage set to 4.

Tell the user: "All batches analysed. Now synthesising everything into your migration files. This takes 2-5 minutes."

Read all the analysis-NNN.json files. These are much smaller than the raw batches (typically 2-5KB each). Combine the insights with the user's interview answers (from progress.json if resuming) to produce the final outputs.

Use the synthesis prompt from references/synthesis-prompt.md as your guide. The outputs are:

1. User Profile (claude-profile.md)

A comprehensive "about me" context document. This covers: who they are, what they do professionally, their interests and hobbies, their communication style, their values and priorities, key life context (location, relationships, etc. - only what they've naturally shared in conversations, never inferred or assumed).

This should read like a friend describing them to someone who's about to help them, not like a

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: JamsusMaximus
• Source: JamsusMaximus/chatgpt-migrator
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.