---

name: "version-migration" description: "Plans safe LeRobot v1.6, v2.0, v2.1, and v3.0 dataset migrations with version-matched environments, metadata-layout checks, local or Hub staging, video handling, and rollback controls." disable-model-invocation: true metadata: disco-role: operating license: MIT

LeRobot version migration

Use this route when an existing LeRobot dataset must move between v1.6 and v2.0, v2.0 and v2.1, or v2.1 and v3.0. It is a planning and review route, not a runnable converter. The repository converters are reference-only because they can rewrite local directories, delete metadata, clone Git-LFS repositories, invoke ffmpeg, create tags, upload files, and push to the Hugging Face Hub.

Do not use this route for converting raw HDF5, RLDS/TFDS, AgiBot, RoboMIND, LIBERO, or RoboCasa data. Route those requests to the dataset-specific sub-skill first, then return here only if the resulting LeRobot dataset needs a version migration.

Non-negotiable boundary

• Never run a migration against the only copy of a dataset. Use an immutable source snapshot and a separate destination or disposable test branch.
• Never infer the source version from a directory name or a tag alone. Read and cross-check meta/info.json (or the legacy meta_data/info.json) and inspect representative data, episode, task, stats, and video paths.
• A current LeRobot import is not proof that a historical converter is usable. Resolve the version-specific API imports and constants before touching data. The source evidence mixes lerobot.common.datasets.*, lerobot.datasets.*, and lerobot.datasets.io_utils; current LeRobot commonly exposes LeRobotDataset and LeRobotDatasetMetadata under lerobot.datasets.lerobot_dataset. Treat namespace mismatch as a stop gate.
• Keep --push-to-hub, deletion flags, tag creation, and any Git-LFS operation off until local validation passes and the operator explicitly approves publication.

Route checklist

1. Record source_version, target_version, repo_id if any, local root(s), desired branch, whether videos exist, and the rollback location. Use the exact direction matrix in version-matrix.
2. Confirm the source metadata schema and episode/task indices. Run the read-only static or synthetic checks in metadata layouts before installing or invoking a converter.
3. Select a version-pinned environment. Do not mix the current package with historical imports. Record Python, LeRobot revision, datasets, jsonlines, pyarrow, safetensors, and ffmpeg versions.
4. Choose one source mode:
   • Local: --root is an exact dataset root for v2.0/v2.1/v3.0 routes. For v1.6→v2.0, --local-dir is staging/cache space; the evidence converter still identifies the Hub dataset with --repo-id.
   • Hub: use a pinned revision or tag and download into a new staging root. Treat every upload, delete, tag, or branch operation as a separate approval step.
5. For v1.6→v2.0 only, choose exactly one task source: --single-task, --tasks-col, or --tasks-path. Check episode coverage and task text before starting. See workflows.
6. Make a backup, record a manifest and checksums, and create a non-production test branch if Hub validation is required. Never let an existing _old, _v30, or destination directory be silently reused.
7. Perform a no-write plan review: expected metadata files, data/video path templates, stats representation, episode counts, frame counts, and tag changes. Do not use a hidden wrapper; the source converters are not bundled in this skill.
8. Execute only after approval in the pinned environment, preferably to a new local root. Keep Hub push and cleanup disabled for the first pass.
9. Validate the output as a dataset of the target version, reopen it with the target LeRobot API, compare counts/tasks/stats, and inspect video durations and timestamps. Then review the rollback copy before any publication.
10. Publish to a test branch first. Only after a consumer successfully reads that branch should the operator rename, tag, delete, or replace a production revision.

Direction-specific dispatch

• v1.6 ↔ v2.0: this bundle provides v1.6→v2.0 planning only. There is no reverse converter in the assigned evidence. Expect task annotation, per-episode parquet splitting, stats serialization, and possible Hub/LFS video moves.
• v2.0 ↔ v2.1: this is primarily a stats and codebase_version migration; data files remain in the v2 layout. v2.0→v2.1 computes per-episode stats and checks their aggregate; v2.1→v2.0 writes aggregate stats.json.
• v2.1 ↔ v3.0: this is a physical layout migration. v2.1→v3.0 consolidates parquet/video files and metadata; v3.0→v2.1 splits them back into per-episode files and uses ffmpeg for video segments.

Read the detailed workflows, metadata layouts, and troubleshooting before making a run plan.