IMPORTANT: To view this page as Markdown, append `.md` to the URL (e.g. /get-started.md). For the complete documentation index, see llms.txt.
Skip to main content
For the complete documentation index, see llms.txt. Markdown versions of all pages are available by appending .md to any URL (e.g. /get-started.md).

Bring up a model with MAX skills

You can accelerate bringing a new large language model architecture to MAX using AI coding agents equipped with MAX skills. These skills define automated, step-by-step workflows that let agents inspect Hugging Face checkpoints, scaffold custom architectures from similar models, implement layer-level differences, and run verification loops.

By delegating the mechanical tasks of mapping configurations and remapping weight keys to an agent, you can focus on directing high-level architecture decisions and verifying the final inference results.

You can use import-model to assist in bringing up a model from an existing architecture, and debug-model to track down output divergences when the new model produces incorrect results. When the model serves correctly, the eval-model skill measures its task accuracy on standard benchmarks such as GSM8K and MMLU. You can then compare it against the original model's published scores. Once the model runs correctly, the profile-model skill helps you find where it spends time and whether the GPU is saturated.

Install MAX skills​

To equip your AI coding agent with the model bring-up workflow, you must install the MAX skills.

Install with Claude Code​

Add the Modular plugin marketplace to Claude Code and install the MAX skills plugin:

/plugin marketplace add modular/skills
/plugin install max-skills@modular

The max-skills plugin includes the model lifecycle skills used on this page (import-model, debug-model, migrate-max-v2-to-v3, and eval-model) along with skills to serve, benchmark, and profile models. To install all Modular skills, including the Mojo skills, use skills@modular instead.

Install with npx​

With Codex and other agents, install the skills with Node.js:

npx skills add modular/skills

If you only want to install the model bring-up skill in isolation, specify the --skill flag:

npx skills add modular/skills --skill import-model

To update your skills to the latest version, run:

npx skills update

Install manually​

If you prefer to install the skills manually, clone the official repository:

git clone https://github.com/modular/skills.git

After cloning, copy or symlink the individual skills into your AI agent's configuration directory. For Claude Code, copy the directories into ~/.claude/skills/:

cp -r skills/import-model skills/debug-model skills/migrate-max-v2-to-v3 \
  skills/eval-model ~/.claude/skills/

Consult your specific agent's documentation to find its configuration and skills directory.

Start the model bring-up​

To begin, open your AI coding agent in your project workspace and instruct it to import the model using its Hugging Face model ID.

The following example prompts start the workflow:

Import the Hugging Face model "LGAI-EXAONE/EXAONE-3.5-2.4B-Instruct" into MAX.
Bring up the Hugging Face model "stabilityai/stablelm-2-1_6b" in MAX.

After receiving the prompt, the agent starts the decide and plan phase and presents the bring-up plan for your review.

Debug output divergences​

A brought-up model can load, compile, and generate tokens yet still disagree with the original model. It might return gibberish, pick the wrong greedy token, or stay coherent for a while and then drift. The debug-model skill is a parity-debugging protocol for a model that serves but produces wrong output. For a crash on load or an unfinished module, use import-model.

Invoke the skill once import-model reports a parity or coherence failure, and point it at a reference you can run, such as the same Hugging Face model:

The MAX implementation of "stabilityai/stablelm-2-1_6b" serves but generates incorrect tokens. Use /debug-model to find where it diverges from the reference.

The agent builds a per-layer tensor-dump comparator that records the reference and MAX activations at every layer. It then reads the comparison to localize the divergence:

  • If a specific layer diverges, the agent hunts that part of the module, verifies a candidate fix against the dumps numerically, and only then recompiles.
  • If every layer matches but the generated text still drifts, the model math is likely correct. The agent bisects the decode state (such as the KV cache) and the harness (tokenizer and chat template).

Review each finding and confirm the fix, the same way you steer the bring-up itself. To run the same per-layer comparison yourself, see Layer comparison.

Migrate an existing architecture to ModuleV3​

If you already ported an architecture with the graph API (max.nn.legacy layers and an explicit Graph), the migrate-max-v2-to-v3 skill converts it to ModuleV3. Point the agent at the model's source:

Migrate the MAX architecture in models/my_model/ to ModuleV3 with /migrate-max-v2-to-v3.

The agent leaves the original implementation in place and writes the ModuleV3 version next to it, then confirms that both produce the same greedy tokens on the same inputs. For a registered architecture, the ModuleV3 variant's name ends in _ModuleV3, and max serve --prefer-module-v3 selects it.

How agent-driven model bring-up works​

The import-model skill drives a phased workflow (decide and plan, implement, then verify), and you remain the coordinator and validator at each checkpoint. The agent writes the port with the max.nn module API, as described in the Model bring-up workflow. The sections below describe what the agent delivers in each phase and how you steer it. For the full procedure, see the skill's SKILL.md.

Decide and plan​

The agent first checks whether MAX already registers the model's architectures[0] class. If it does, the agent serves the model with max serve and stops, because the model doesn't need a port.

Otherwise, the agent reads the model's config.json, checkpoint metadata, and model card, and scans for hard blockers such as custom CUDA kernels. It runs list_native_archs.py to list the reference architectures your installed MAX ships, then picks the closest one to copy (such as llama3_modulev3 or olmo3). It compares that architecture's modules with the Hugging Face modeling code and presents a written plan naming the architecture it will copy and a delta list, one row per difference between the copy and the target.

Review the plan before authorizing the agent to write code. Confirm that it chose the right architecture to copy and identified every unique layer property described in the model's paper or Hugging Face model card.

Implement​

After you approve the plan, the agent runs scaffold.py --start-from <arch> to write a starting package:

  • model_config.py: the config class, plus the Hugging Face fields the copied architecture doesn't read.
  • model.py: the pipeline model, building your root module and placing it on the device or device mesh.
  • weight_adapters.py: an adapter that delegates to the copied renames.
  • {model_name}.py: your root module.
  • arch.py: a registration that carries the copied batch processor.

--full-copy copies every file and renames its classes, which a port needs when its module tree differs from every architecture MAX ships, as with Gemma 3 and Llama 4.

The scaffold's default mode writes subclasses, so the package starts out importing the architecture you chose. The skill's first implementation step turns each of those imports into a copy: the files move into your package and the imports point at them. A shipped model directory imports its own files and the shared MAX libraries, and no other model, and its BUILD.bazel names no other architecture directory. Where several models need the same symbol, the skill moves it into the shared libraries.

The package still runs the copied model's computation until the agent implements each row of the delta list as max.nn modules, maps the remaining config fields, and rewrites the weight adapter for your checkpoint.

Make sure the agent updates the copied docstrings and comments so they describe your model. A copied file keeps the original text until someone rewrites it. The skill requires an audit of that text before it reports the implementation as complete.

Verify and validate​

Before serving, the agent runs preflight gates and local checks. These include an import smoke test, a lazy build of the module, and a diff between the adapter's keys and the module's parameter names. It then serves the model locally to confirm that it compiles and loads weights without orphan keys. Finally, it compares greedy token generation against the reference Hugging Face model.

Review the generated output and verification reports. The skill is still evolving and can't guarantee a correct port. If you see gibberish or incoherent text, the debug-model skill takes the model from here to isolate and resolve the divergence.

Greedy token comparison confirms the model matches the reference on a handful of prompts. To confirm accuracy holds across a full benchmark, the eval-model skill runs standard datasets against the served model and compares the scores against the original model's model card.

Next steps​

Once the agent has created and verified your new model architecture, you can serve and deploy it:

  • Serve custom model architectures: Learn how to package and run your new custom model architecture using max serve.
  • Evaluate model accuracy: Use the eval-model skill to benchmark your served model on standard datasets and compare the scores against the original model.
  • Logit comparison and Layer comparison: Validate the architecture yourself, measuring logit similarity and localizing the first layer that diverges from the reference.
  • Model bring-up workflow: Read the detailed manual bring-up steps to better understand module compilation, memory sizing, and weight remapping.
  • Set up AI coding: Configure your development environment with rules and context files for general AI-assisted development.

Was this page helpful?