mlx-metal-kernels-skill

A practical skill pack for writing custom Metal compute kernels using MLX (mx.fast.metal_kernel) on Apple Silicon.

Quick start

python -m venv .venv && source .venv/bin/activate
pip install -U mlx
python skill/scripts/rmsnorm_kernel.py
python skill/scripts/softmax_kernel.py
python -m skill.tests.smoke_test

If you just need task routing and patterns, start with skill/SKILL.md.

Compatibility

• macOS on Apple Silicon (Metal-capable GPU)
• Python 3.12+
• MLX 0.30.6+

Repository docs

• skill/SKILL.md: skill entrypoint and routing guide
• docs/USING_WITH_CLAUDE_CODE.md: using this project from Claude Code
• docs/USING_WITH_CODEX_CHATGPT.md: using this project from Codex (ChatGPT)
• CONTRIBUTING.md: contribution workflow and review expectations
• SECURITY.md: vulnerability reporting policy
• RELEASE_CHECKLIST.md: pre-publish and release checklist

Structure

• skill/SKILL.md — primary skill guide / index of patterns
• skill/scripts/ — runnable examples
• skill/kernels/ — reusable helpers (autotune + cache, scalar buffers, device capability checks)
• skill/tests/ — smoke tests for local/CI use
• skill/references/ — deep-dive reference docs

Repo Layout

mlx-metal-kernels-skill/
├── README.md
├── CONTRIBUTING.md
├── SECURITY.md
├── RELEASE_CHECKLIST.md
├── docs/
│   ├── USING_WITH_CLAUDE_CODE.md
│   └── USING_WITH_CODEX_CHATGPT.md
├── .github/workflows/ci.yml
└── skill/
    ├── SKILL.md
    ├── manifest.txt
    ├── kernels/
    ├── scripts/
    ├── tests/
    └── references/