Migrate Max V2 to V3

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

213 stars 22 forksAI, LLMs & Agents Plugin marketplace

Install

Claude Code plugin
/plugin marketplace add modular/skills

The repo is a Claude Code plugin marketplace. Run /plugin afterwards to pick the plugin that includes this skill.

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add modular/skills --skill migrate-max-v2-to-v3
Manual install
git clone --depth 1 https://github.com/modular/skills.git /tmp/skills
mkdir -p ~/.claude/skills
cp -r /tmp/skills/migrate-max-v2-to-v3 ~/.claude/skills/migrate-max-v2-to-v3

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# 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>
```
Read the full skill on GitHub

Details

Skill name
migrate-max-v2-to-v3
Repository
modular/skills
Path
migrate-max-v2-to-v3/SKILL.md
Repo updated
18 November 2026

FAQ

What does the Migrate Max V2 to V3 skill do?

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

How do I install the Migrate Max V2 to V3 skill?

Claude Code plugin: /plugin marketplace add modular/skills. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Migrate Max V2 to V3 popular?

It lives in modular/skills, which has 213 GitHub stars and 22 forks.

Related skills

Benchmark Model

213

modular/skills

Benchmark a model served on MAX with the `max benchmark` command: measure throughput (tokens/sec), latency (TTFT, TPOT, inter-token latency), and GPU utilization by driving load against a running `max serve` endpoint. Use this whenever the user wants to benchmark, load-test, or measure the performance of a MAX model, get tokens-per-second / TTFT / TPOT numbers, run a concurrency or request-rate sweep, compare latency vs throughput, size a deployment, or produce benchmark JSON, even if they don't say "benchmark" by name. Also use when a `max benchmark` run fails to connect or reports zero/garba

AI, LLMs & Agents22

Debug Model

213

modular/skills

Debug a MAX model that loads, compiles, serves, and generates tokens but whose output disagrees with a reference implementation. Use whenever parity debugging stalls on scalar taps, the model returns gibberish or wrong greedy tokens, logit cosine is high but argmax differs, or generation is coherent then diverges. Applies during an architecture port, a quantization bring-up, a multi-GPU conversion, or after a MAX upgrade. Triggers on "parity failure", "silent corruption", "logits match but tokens diverge", "top-1 mismatch", "greedy divergence", and "model serves but generates garbage". Not for

AI, LLMs & Agents22

Eval Model

213

modular/skills

Measures the task accuracy of text models served by MAX using standard benchmarks such as GSM8K, MMLU, HellaSwag, ARC, AIME, GPQA, TruthfulQA, WinoGrande, and BABILong. Use when benchmarking a served model, comparing it with model-card or reference scores, verifying that a new MAX model produces correct answers, or running repeatable dataset evaluations against a MAX OpenAI-compatible endpoint.

AI, LLMs & Agents22

Profile Model

213

modular/skills

Profile a model running on MAX to find where it spends time and whether the GPU is saturated. Use when the user asks to "profile my model," "where is my model spending time," "why is inference slow," "is my GPU being utilized," "how much GPU am I using," "get a kernel breakdown," "capture an nsys/rocprof/ncu trace of max serve," or wants to measure MAX inference performance. Works for any model MAX can run — built-in architectures and custom ones loaded with --custom-architectures — from a pip or pixi install (max generate, max serve, or a Python script) on NVIDIA or AMD GPUs. Decide cheapest-

AI, LLMs & Agents22

Import Model

213

modular/skills

Use when importing a new model architecture into MAX from a Hugging Face model ID. Triggers on: "import a model into MAX", "add model to MAX", "bring up <HF model> in MAX". Workflow: inspect the Hugging Face config and modeling code, then scaffold from a similar ModuleV3 architecture. Implement each layer as a max.nn Module that matches HF, serve, then verify against the Hugging Face reference. When the server runs but output is wrong (gibberish, greedy mismatch, coherent-then-diverges), load debug-model for the divergence hunt.

AI, LLMs & Agents22

Serve Model

213

modular/skills

Serve a model with MAX's `max serve` command: set up the environment (pixi or uv with the max-nightly conda channel / nightly wheel index), point the server at a Hugging Face repo or local checkpoint, target a custom architecture with `--custom-architectures`, and pick the right serve flags for the model. Use this whenever the user wants to run, launch, start, or host a model on MAX, bring up an OpenAI-compatible endpoint, serve a custom/ported architecture, debug a `max serve` startup failure, or figure out which serve flags (devices, quantization-encoding, max-length, task, trust-remote-code

AI, LLMs & Agents22

Browse the most popular Claude skills, all ai, llms & agents skills, or write your own with the skills generator.