Godot Version Migration Agent Skill

Godot Version Migration

Orchestrator for engine version upgrades from early Godot through the library target. Domain Skills document current APIs; this hub owns the upgrade path.

Library target: Godot 4.7+

Corpus: docs changelog · interactive changelog · download archive · GitHub releases · migrating index

NEVER Do

• NEVER skip majors — route 1.x → 2.x → latest 3.x → 4.0 before any 4.x minor ladder.
• NEVER skip 4.x hops — upgrade 4.0 → 4.1 → … → 4.7 one minor at a time; stabilize after each hop.
• NEVER claim automatic 1.x→4.x conversion or bit-exact autopilot.
• NEVER treat Domain Skill bodies as migration changelogs — load references/<topic>.md (mirrored from each skill’s references/migration-notes.md).
• NEVER load all module notes at once — only subsystems present in the project.
• NEVER mix server/client Godot minors for high-level multiplayer (especially across 4.2→4.3 SceneMultiplayer protocol changes).
• NEVER choose Mesh “Restart & Upgrade” without VCS backup (4.1→4.2 mesh format).
• NEVER run the 3→4 converter without a full backup (tool does not backup).

Version detect

• Read project.godot (config_version, config/features) or legacy engine.cfg.
• Ask the user if files are ambiguous.
• Map to an era in references/era-index.md.

Workflow router (MANDATORY)

| Detected era | Load | Do NOT |

|--------------|------|--------|

| 1.x / early 2 | legacy/pre-2-context.md | Invent a 1→4 converter |

| 2.x | legacy/2-to-3.md then stabilize on latest 3.x | Jump straight to 4.7 notes |

| 3.x | bridges/3-to-4.md + official 3→4 guide | Skip latest-3.x stabilize gate |

| 4.x < 4.7 | Official hop guide + hop-index.md module notes for touched systems | Skip minors |

| Already 4.7+ | godot-master / Domain Skills | Treat this hub as a coding tutorial |

Steps (4.x minors)

• While current < 4.7, perform exactly one hop to current + 0.1.
• Open the official upgrading page for the destination version.
• From hop-index.md, open only module notes for subsystems present in the project.
• Apply fixes; open in the new editor; playtest; repeat.

Hop table

Majors / bridges

| Era | Resource |

|-----|----------|

| 1.x archaeology | legacy/pre-2-context.md |

| 2.x → 3.x | legacy/2-to-3.md |

| 3.x → 4.0 | bridges/3-to-4.md · official guide |

| Ladder overview | era-index.md |

4.x minors

| Hop | Official guide |

|-----|----------------|

| 4.0 → 4.1 | https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.1.html |

| 4.1 → 4.2 | https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.2.html |

| 4.2 → 4.3 | https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.3.html |

| 4.3 → 4.4 | https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.4.html |

| 4.4 → 4.5 | https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.5.html |

| 4.5 → 4.6 | https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.6.html |

| 4.6 → 4.7 | https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.7.html |

Cross-skill checklist: references/hop-index.md

Module directory

Mirrored Domain Skill migration notes live at references/<topic>.md (e.g. references/2d-physics.md). Hub-native legacy/, bridges/, and era-index.md are not Domain Skill mirrors.

sync_godot_version_migration.py --all

Reference

Official docs

• Migrating to a new version
• Upgrading from Godot 3 to Godot 4
• Docs changelog

Related Skills

Master

• godot-master — Library router for current Domain Skill modules after migration is complete.

Downstream / consumers

• godot-analyst — Score architecture on the target APIs after hops land.
• godot-auditor — Never-list / legacy-syntax verification after upgrades.
• godot-builder — CI / headless bake against the new engine target after each hop.

Complements

• godot-project-foundations — Project settings / structure once on the target version.
• godot-gdscript-mastery — Typed GDScript 2.0 idioms after 3→4 / 4.x language hops.
• godot-export-builds — Re-validate exports after each hop that touches platforms.