migrate-max-v2-to-v3 — Claude Code skill: what it does and install
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().
Apache-2.0 324 installs ★ 213 updated 2026-11-07
npx skills add modular/skills --skill migrate-max-v2-to-v3 -a claude-codeWhat migrate-max-v2-to-v3 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.
What it helps with
- rewrite layers from
max.nn.legacytomax.nn - replace deprecated
TensorValueobjects withTensor - switch explicit
Graphconstruction toF.lazy()andcompile() - align checkpoint weight keys with the new module hierarchy
Example prompts for the agent
- Migrate the model in
models/my_model.pyfrom V2 graph API to ModuleV3 - Convert
TensorValueusages toTensorintransformer.py - Update imports from
max.nn.legacytomax.nnand configurecompile()
How to install migrate-max-v2-to-v3
1Skills CLI (Vercel)
npx skills add modular/skills --skill migrate-max-v2-to-v3 -a claude-code2Manually: put the files in place
~/.claude/skills/migrate-max-v2-to-v3/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/migrate-max-v2-to-v3/
1Skills CLI (Vercel)
npx skills add modular/skills --skill migrate-max-v2-to-v3 -a codex2Manually: put the files in place
.agents/skills/migrate-max-v2-to-v3/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add modular/skills --skill migrate-max-v2-to-v3 -a cursor2Manually: put the files in place
.cursor/skills/migrate-max-v2-to-v3/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install modular/skills migrate-max-v2-to-v32Manually: put the files in place
.github/skills/migrate-max-v2-to-v3/SKILL.md1Skills CLI (Vercel)
npx skills add modular/skills --skill migrate-max-v2-to-v3 -a gemini-cli2Platform CLI
gemini skills install https://github.com/modular/skills --path migrate-max-v2-to-v3Manually: put the files in place
.devin/skills/migrate-max-v2-to-v3/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add modular/skills --skill migrate-max-v2-to-v3 -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about migrate-max-v2-to-v3
How to install migrate-max-v2-to-v3 in Claude Code?
Run npx skills add modular/skills --skill migrate-max-v2-to-v3 -a claude-code in your terminal. The skill file is placed in ~/.claude/skills/migrate-max-v2-to-v3/SKILL.md.
What does migrate-max-v2-to-v3 do?
It provides a guided workflow to port MAX models from legacy graph construction to ModuleV3, updating tensor types, layer signatures, and weight compilation.
What prerequisites are needed to verify the migration?
You need MAX installed via pip or pixi, the original model code, and a GPU to compare greedy output tensors against the V2 baseline.
Source text
SKILL.md · Apache-2.0
---
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
`DeviceRef` from `max.graph` for input specs. A file that hits both is
mixed. Read it before migrating anything.
### 2. Keep the V2 code, add the V3 variant
Leave the V2 implementation untouched so it keeps working while the V3
variant is under construction. Put the V3 code alongside it: a
`<name>_modulev3` directory when migrating a registered architecture, or a
new module file when the model lives in your own package. When migrating a
registered architecture, name the V3 variant with the `_ModuleV3` suffix.
`max serve --prefer-module-v3` selects it while the V2 name keeps serving
by default.
### 3. Rewrite imports
```python
# REMOVE:
from max.graph import Graph, TensorValue, BufferValue, ops
from max.nn.legacy.layer import Module, LayerList
from max.nn.legacy.linear import Linear
from max.nn.legacy.norm.rms_norm import RMSNorm
# ADD:
from max import functional as F
from max.tensor import Tensor
from max.nn import Module
from max.nn.linear import Linear
from max.nn.norm import RMSNorm
from max.nn.sequential import ModuleList
# KEEP (TensorValue-free, shared with V2):
from max.nn.kv_cache import KVCacheParams, KVCacheParamInterface
from max.nn.attention_mask import MHAMaskVariant
```
- `TensorType` and `DeviceRef` stay from `max.graph`. They define input
specs, not graph values.
- `max.nn.legacy` imports are fine when the imported class doesn't use
`TensorValue`.
- `PagedCacheValues` comes from
`max.nn.common_layers.kv_cache` for the V3 type. `max.nn.legacy`
exports a `PagedCacheValues` of its own, an alias for the V2 input type
without `from_upstream()`. Import from the `max.experimental` path to
get the V3 type.
### 4. Rewrite the module surface
- `__call__()` becomes `forward()`.
- `TensorValue` and `BufferValue` become `Tensor`.
- `Module` takes the call signature:
`class MyModel(Module[[Tensor, ...], tuple[Tensor, ...]])`. Prefer
specific types, and use `...` only when `forward()` has `*args`.
- Layer constructors take keyword args and drop `dtype=` and `device=`.
V3 uses default dtype and device contexts, and `model.to(device)` moves
the module to one device after construction.
- `LayerList` becomes `ModuleList` from `max.nn.sequential`.
`ModuleList` subclasses `list`, so it takes a single iterable:
`ModuleList(layers)`. `ModuleList(*layers)` raises `TypeError`.
- Parameters are plain `Tensor` objects. Create them with `Tensor.zeros()`,
`max.functional.random.*`, and similar factories.
### 5. Rewrite operations
`ops.*` becomes `F.*` (`ops.gather()` → `F.gather()`). Most shape ops are
methods on `Tensor`: `reshape()`, `transpose()`, `permute()`, `squeeze()`,
`unsqueeze()`, `split()`, `cast()`. `flatten()` is the exception. It's
functional-only (`F.flatten(tensor, start_dim)`).
### 6. Replace graph building with `compile()`
V2:
```python
nn_model = MyModel(config)
nn_model.load_state_dict(state_dict)
with Graph("my_model", input_types=input_types) as graph:
outputs = nn_model(*graph.inputs)
graph.output(*outputs)
model = session.load(graph, weights_registry=state_dict)
```
V3:
```python
with F.lazy():
nn_model = MyModel(config)
nn_model.to(device)
model = nn_model.compile(*input_types, weights=state_dict)
```
- `F.lazy()` wraps construction and records weight tensors symbolically.
The checkpoint passed to `compile(weights=...)` replaces them.
- Every parameter needs a state-dict entry of matching shape and dtype:
a missing one raises `KeyError` and a mismatched one `ValueError`. An
entry that matches no parameter is left out without an error, so diff
the state-dict keys against `parameters` after migrating (step 7).
- A dtype mismatch between a parameter and its loaded tensor raises by
default. Pass `auto_cast=True` to permit safe dtype casts.
- Call the compiled model directly (`model(tokens, ...)`). Compiled outputs
are `Tensor` objects. Code that consumed `Buffer` outputs reads the
buffer via `.driver_tensor`.
### 7. Align weight names with the compiled hierarchy
`compile(weights=...)` resolves names from the root compiled module's
attribute hierarchy. When migration introduces or renames wrapper
attributes, checkpoint key mappings must follow: a root module storing
`self.language_model = ...` needs every inner weight prefixed with
`language_model.`. After migrating, check that every state-dict key is a
valid attribute path from the root module.
Tied embeddings need explicit handling: conditionally create `lm_head`, and
multiply by `embed_tokens.weight.T` in `forward()` when
`tie_word_embeddings` is set. Keep one copy of the shared weight in the
state dict.
### 8. Move the KV cache unflatten into `forward()`
The KV cache parameter types stay in `max.nn.legacy`. The values type has a V3
home in `max.nn.common_layers.kv_cache`. Use the methods on
`kv_params` plus `PagedCacheValues.from_upstream()`:
```python
def forward(self, tokens: Tensor, ..., *variadic_args: Tensor):
kv_inputs = iter(arg._graph_value for arg in variadic_args)
symbolic_inputs = self.kv_params.unflatten_kv_inputs(kv_inputs)
kv = PagedCacheValues.from_upstream(symbolic_inputs, tokens.mapping)
```
You need the `._graph_value` extraction: `variadic_args` arrive as
`Tensor` objects while the unflatten methods expect raw graph values. For
sliding plus global attention, declare `MultiKVCacheParams` and use
`unflatten_basic_kv_tree()`, wrapping each tree with its own
`PagedCacheValues.from_upstream()`.
### 9. Port sharding when the V2 model is sharded
V2 sharding sets a `ShardingStrategy` on each layer and calls
`.shard(devices)` to get a per-device module list. V3 puts a `DeviceMesh` on
the model and a placement mapping on each weight:
```python
from max.nn.common_layers.linear import row_parallel
from max.tensor.sharding import DeviceMesh
model.mesh = DeviceMesh(devices, (n_devices,), ("tp",))
linear = row_parallel(Linear(in_dim, out_dim))
```
`col_parallel()` and `row_parallel()` set which mesh axis each weight
dimension shards over, and V3 has no per-device module list. The V2
distributed machinery maps onto V3 as follows:
- **`Allreduce` and `Signals`**: the sharding solver reads the tensors'
placements and inserts the collective each op needs. For example, adding
a row-parallel output (a `Partial` sum) to a replicated residual
all-reduces it. Call
`F.allreduce_sum()`, `F.reduce_scatter()`, or `F.allgather()` where the
model controls the reduction. `compile()` adds the signal buffers the
collectives use as graph inputs and supplies them at run time.
- **`.shard()` and per-device lists**: construct the model inside
`default_device(mesh)`, and each weight is created on the mesh with the
placement it declares. `Module.to()` moves a module to one device only and
raises for a multi-device mesh. Per-device code runs through
`F.functional()`, or through `t.local_shards` and
`Tensor.from_shard_values()`.
- **Expert parallelism**: V3 reuses `EPBatchManager`. Its
`comm_buffers()` returns the communication buffers as `Tensor` values,
and the MoE layer passes each device's shard to the dispatch calls as a
`TensorValue`. For registered ModuleV3 decoders, the shared runtime uses
`DeploymentConfig` / `ExpertParallelDeploymentConfig` to configure EP;
see the [registration reference](references/module-registration.md).
`_init_distributed_runtime()` is an existing custom-pipeline integration
pattern, not boilerplate to add to a registered architecture.
`gemma3_modulev3/` (TP) and `deepseekV3_modulev3/` (TP, TP + EP, DP + EP)
show each pattern.
### 10. Verify against V2
Run both implementations on the same inputs and compare greedy tokens
(and logits where convenient). Identical outputs confirm the migration.
Run mypy over the migrated module. V3 relies on the `Module[[...], ...]`
signatures, so type errors point to migration bugs.
## Reference implementations
The registered architectures ship as readable Python source in the
installed MAX package, under `max/pipelines/architectures/`. The V3
migrations to read:
- Single-GPU V3: `olmo3/`, `gpt_oss_modulev3/`, `llama3_modulev3/`
- Sharded V3: `kimik2_5_modulev3/`, `gemma3_modulev3/`, `deepseekV3_modulev3/`
- Hybrid attention with recurrent state: `nemotron_h_modulev3/`
- V2 for comparison: `gpt_oss/`, `llama3/`
## When there is no `Tensor` equivalent
Every graph op and kernel is callable from V3: `F.functional(fn)` turns a
function over `TensorValue` into one over `Tensor`. The options, and the
wrapper pattern for bridging a per-device `TensorValue` helper into a
`Tensor` API, are in
[references/v2-v3-basics.md](references/v2-v3-basics.md).
The wrapper rules, which a reviewer enforces:
- Wrap **one** graph op or kernel per `F.functional` call. A body that calls
two ops hides its intermediate placements from the sharding rules, and one
unplaceable step silently turns the whole body into per-device code.
- `TensorValue` appears only in a wrapper's body. A helper that takes or
returns one for any other reason becomes a function of `Tensor`s.
- Code that must read each device's own rows — a replica's row offsets —
goes in `F.call_on_mesh(fn, mesh, out_specs=...)`. For one raw graph op,
a rule-less `F.functional(ops.x)` is the shorthand; claim its `Unknown`
result with `rebind_mapping()`. An `Unknown()` operand needs a rule row
that names it.
© modular · Apache-2.0 · modular/skills