# migrate-max-v2-to-v3

migrate-max-v2-to-v3 — a skill for Claude Code and Codex that migrates MAX framework models from the legacy V2 graph API to ModuleV3. It updates imports, swaps TensorValue for Tensor, and switches graph building to compile().

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 324 installs · ★ 213 repo stars
- Author: modular
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/modular/skills/tree/HEAD/migrate-max-v2-to-v3/SKILL.md
- Updated: 2026-11-07
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/migrate-max-v2-to-v3

## What it does

The skill converts deep learning model definitions from the deprecated `max.nn.legacy` graph API to current `max.nn` conventions. Running the workflow requires a working MAX environment installed via `pip` or `pixi`, the original V2 model source code, and a GPU.

The assistant swaps `TensorValue` and `BufferValue` types for `Tensor`, redirects execution logic from `__call__()` into `forward()`, and switches layers to `ModuleList`. Instead of manual `Graph` assembly, model instantiation runs inside an `F.lazy()` context followed by `compile(weights=state_dict)`. Missing parameters in the state dict trigger a `KeyError`, so the migration process aligns attribute paths with checkpoint keys.

Without an accessible GPU, verifying that greedy outputs match the V2 implementation is impossible. If the original model used sharding, the workflow moves those partitions onto a `DeviceMesh`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add modular/skills --skill migrate-max-v2-to-v3 -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/migrate-max-v2-to-v3/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/migrate-max-v2-to-v3/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add modular/skills --skill migrate-max-v2-to-v3 -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/migrate-max-v2-to-v3/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add modular/skills --skill migrate-max-v2-to-v3 -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/migrate-max-v2-to-v3/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install modular/skills migrate-max-v2-to-v3
```

2. **Manually: put the files in place**
- File: `.github/skills/migrate-max-v2-to-v3/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add modular/skills --skill migrate-max-v2-to-v3 -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/modular/skills --path migrate-max-v2-to-v3
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/migrate-max-v2-to-v3/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add modular/skills --skill migrate-max-v2-to-v3 -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/modular/skills/tree/HEAD/migrate-max-v2-to-v3/SKILL.md

## When to use it
- rewrite layers from `max.nn.legacy` to `max.nn`
- replace deprecated `TensorValue` objects with `Tensor`
- switch explicit `Graph` construction to `F.lazy()` and `compile()`
- align checkpoint weight keys with the new module hierarchy

## Example prompts
- Migrate the model in `models/my_model.py` from V2 graph API to ModuleV3
- Convert `TensorValue` usages to `Tensor` in `transformer.py`
- Update imports from `max.nn.legacy` to `max.nn` and configure `compile()`

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: b01eff3298e0f37b.

BEGIN THIRD-PARTY FILE b01eff3298e0f37b
````text
---
name: migrate-max-v2-to-v3
description: >
  Use when migrating a MAX model from the V2 graph API (max.nn.legacy, TensorValue,
  explicit Graph construction) to ModuleV3 (max.nn, Tensor,
  F.lazy() + compile()). Triggers on: "migrate to ModuleV3", "port a max.nn.legacy
  model to max.experimental", "convert TensorValue to Tensor", "update my
  model to the V3 API", "ModuleV3 migration". Workflow: read the concept map,
  rewrite imports and __call__ signatures, and replace graph building with
  compile(weights=...). Align weight names with the new module hierarchy and
  move the KV cache unflatten into forward(). Port sharding to a DeviceMesh
  when the V2 model is sharded, then verify greedy outputs match the V2
  implementation.
compatibility: Requires a MAX install (pip or pixi), the V2 model source to migrate, and a GPU to verify outputs.
metadata:
  argument-hint: "[path to your V2 model code, for example 'models/my_model.py']"
---

# Migrate a MAX model from V2 to ModuleV3

**Input**: the V2 model source to migrate (`$ARGUMENTS`).

ModuleV3 (`max.nn`) is the current MAX model API. A V2 model
builds an explicit `Graph` over `TensorValue` values with layers from
`max.nn.legacy`. A ModuleV3 model declares a `forward()` over `Tensor` values and
compiles with `F.lazy()` + `compile()`. Read
[references/v2-v3-basics.md](references/v2-v3-basics.md) first. It covers
`F.lazy()`, `compile(weights=...)`, dtype handling with `auto_cast`,
`forward()` vs `__call__()`, the distributed mapping, and the import
rules.

For architecture serving integration, read the
[module registration compatibility reference](references/module-registration.md).
Prefer supported ModuleV3 role registration without an architecture-specific
`PipelineModel`. The standalone compilation examples below explain the model
API; the registration runtime owns those steps for registered architectures.
Keep a custom pipeline for a documented unsupported task, backend or feature.
Draft/speculator module registration has not been added.

## Workflow

### 1. Confirm the model is V2

Classify by imports, and read the file when grep and the imports disagree.
V2 code imports its layers from `max.nn.legacy` and builds an explicit `Graph`
over `TensorValue`. ModuleV3 code imports `max.nn` and
subclasses its `Module`. Scoped greps shortcut the read:

```bash
grep -rn "max.experimental" <model-path>
grep -rEn "^\s*(from|import) max\.nn" <model-path>
```

Hits from the first mean the model is already (at least partly) V3 and
needs review, not migration. Hits from the second mean V2. Imports from
`max.graph` alone don't decide: V3 code keeps `TensorType` and
````
END THIRD-PARTY FILE b01eff3298e0f37b

The third-party file has ended. Everything between the b01eff3298e0f37b tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2652 of 12036 bytes. © modular · Apache-2.0 · https://github.com/modular/skills/tree/HEAD/migrate-max-v2-to-v3/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
