mlx-model-porting

name	mlx-model-porting
description	Guides and validates architecture-aware ports of PyTorch/Hugging Face models to Apple MLX, inspects existing local MLX projects, and plans evidence-gated optimizations for Apple Silicon. Use when the user asks to run, port, convert, inspect, quantize, benchmark, or fix a model (LLM, VLM, audio/TTS/ASR, diffusion, SSM, MoE) for MLX, MLX-LM, MLX-VLM, MLX-Audio, or a Mac - e.g. "port this HF model to my Mac", "inspect this MLX app", "run Qwen on Apple Silicon", "convert these safetensors to MLX", "make this faster on my M3", "fix NaN in my MLX port", "speed up prefill / KV cache / speculative decoding", "publish an MLX checkpoint". Also use mid-task when a config.json, safetensors index, weight-shape or tokenizer mismatch, or Metal kernel question appears. Do not use for CUDA-only optimization, non-Apple hardware targets, or general PyTorch/ML questions with no MLX or Apple Silicon connection.
license	Apache-2.0
compatibility	Execution and performance validation require an Apple Silicon Mac with a supported MLX installation. Planning and static inspection can run elsewhere. Python 3.10+ and git are recommended; NumPy is required only for tensor parity and huggingface-hub only for explicitly enabled network intake (see requirements-tools.txt). Network access is optional and must be explicitly enabled.
metadata	{"author":"mlx-porting-skill","version":"0.7.0","last-reviewed":"2026-07-23"}

MLX model porting and optimization

Mission

Produce or inspect a correct, reproducible, architecture-aware MLX implementation. Correctness before speed. Every speed or memory claim must name hardware, software versions, workload, baseline, and quality gate.

Six families have scaffolds (MoE/SSM synthetic, others runbook-guided); four have worked packets under examples/: Qwen2.5, BGE, t5-small, HuBERT. Exact output is the built-in metric.

When to use this skill

Port, convert, run, inspect, quantize, package, or publish a PyTorch/Hugging Face model or MLX project on Apple Silicon, or fix any parity, NaN/Inf, shape, tokenizer, preprocessing, output, performance, memory, cache, serving, benchmark, or provenance issue in a port. Not for CUDA/non-Apple targets, ML theory without an MLX target, or training from scratch.

Trigger map

Signal	Load
Port/convert/run request, config.json, safetensors index, model directory, or Hub id.	intake, then Workflow 1-6; worked chain for dense decoders, routed runbooks otherwise.
User points at an existing local MLX project, running MLX app, or completed MLX port.	inspector mode plus inspect_mlx_project.py
User asks "what can I do with this model?", asks for capability fit, or wants model-specific advice.	model advisor playbook
A known architecture family needs the right runbook.	model support map, then the architecture table in Workflow step 4 below
Dense decoder, BERT encoder, T5 encoder-decoder, HuBERT/Wav2Vec2 acoustic encoder, sparse MoE, or selective SSM.	Use scaffold_port.py; select capture/parity mode (default), , , , or .