v2.0.0 — Rename to mlx-porting + checkerboard pitfall + CI
Breaking
- Skill directory renamed
porting-pytorch-to-mlx/→mlx-porting/. Same move inside the packaged.skilltarball. - Frontmatter
nameupdated accordingly:mlx-porting. - Existing v1.0.0 installs (the
~/.claude/skills/porting-pytorch-to-mlx/layout) will keep working but will NOT receive these updates — reinstall from source or download the newmlx-porting.skillartifact below.
Added
- Pitfall #7 — The checkerboard trap in
references/common-pitfalls.md. Covers the four recurring causes (mx.tilevsmx.repeat, pixel-shuffle axis order, text-encoderhidden_states[-2]off-by-one, scheduler dtype leaking fp32 into a bf16 DiT) and a three-test diagnostic procedure to run before shipping every port. - SKILL.md upgrades: new reading-time checklist bullet flagging the checkerboard trap, plus a caveat in Step 5 that small-scale random-weight parity is necessary but insufficient.
- Helpers in
scripts/parity_helpers.py: `detect_checkerboard(image)` (autocorrelation-based) and `noise_decode_check(decode_fn, shape)` to wire the diagnostic as a permanent smoke test. - GitHub Actions:
- `ci.yml` validates frontmatter, `evals.json` schema, cross-references, and python syntax on every push and PR, plus a `.skill` packaging smoke test.
- `release.yml` auto-builds `mlx-porting.skill` on tag push and attaches it to the release (this release is the first to use it).
- CI badge on the README.
Why this matters
Every MLX port I've shipped has hit a checkerboard-looking output at some point because layer-level parity passes with random weights at small scale but the bug only manifests at production scale. This release codifies the fix: the 3-test diagnostic catches 95% of the class in under 90 seconds, and the rule "never tweak sampling parameters to mask a spatial-operator bug" is now part of the checklist.
Asset
`mlx-porting.skill` below is produced by the new release workflow. Drop it into Claude Code via `/skill install mlx-porting.skill` or unpack under `~/.claude/skills/`.