Skip to content
Skills Library
Programming · Building & coding

contributing

/contributing

Use this skill when the user wants to contribute to MLX-VLM — opening a PR, where model code/config/tests go, backward-compatible config args, running the test suite, code formatting and the pre-commit hooks (black, clang-format), and PR expectations (tests, review, perf evidence). Use it to set up a change so it passes review.

Repository
mlx-vlm ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use this skill when the user wants to contribute to MLX-VLM — opening a PR, where model code/config/tests go, backward-compatible config args, running the test suite, code formatting and the pre-commit hooks (black, clang-format), and PR expectations (tests, review, perf evidence). Use it to set up a change so it passes review.

Original author description

Use this skill when the user wants to contribute to MLX-VLM — opening a PR, where model code/config/tests go, backward-compatible config args, running the test suite, code formatting and the pre-commit hooks (black, clang-format), and PR expectations (tests, review, perf evidence). Use it to set up a change so it passes review.

How it works

  1. Setup
  2. Where things go
  3. Run the tests
  4. Formatting — install and run pre-commit
  5. PR expectations
  6. Routing
Original SKILL.md headings · 62 lines, 421 words
SKILL.md preview
---
name: contributing
description: Use this skill when the user wants to contribute to MLX-VLM — opening a PR, where model code/config/tests go, backward-compatible config args, running the test suite, code formatting and the pre-commit hooks (black, clang-format), and PR expectations (tests, review, perf evidence). Use it to set up a change so it passes review.
---

# Contributing to MLX-VLM

Use this workflow to shape a contribution so it lands cleanly. It reflects the current `mlx_vlm/` layout (note: `CONTRIBUTING.md` still points at an older `src/` layout — the real paths are below).

## Setup

```bash
git clone https://github.com/<you>/mlx-vlm && cd mlx-vlm
uv pip install -e .            # editable install (or: pip install -e .)
```

## Where things go

- **Model code:** `mlx_vlm/models/<model_type>/`, and the file name matches the `config.json` `model_type` (e.g. `llava`). A new kernel or helper goes in **its own file in that model directory**, not bolted into `language.py`. To add a whole new model, use `Skill("mlx-vlm-skills:add-new-model")`.
- **Config args:** add to the model's `ModelConfig` (in `<model>/config.py`) with an inline `# comment`, and keep them **backward-compatible** — a default of `None`/`0`/`False` must reproduce the original behavior so existing checkpoints and configs are unaffected. Gate new features so they are opt-in.
- **Tests:** add to `mlx_vlm/tests/test_models.py` as a **class per feature** (e.g. `TestMyFeature`). Do not create a standalone `test_<feature>.py` — repo convention keeps model tests in `test_models.py`. Prefer cheap synthetic/random-weight tests (tiny configs) and check exactness against the original path in the degenerate limit (feature disabled == baseline).

## Run the tests

```bash
cd mlx_vlm && uv run --with pytest python -m pytest tests/test_models.py -q -k "<ClassName>"
```

## Formatting — install and run pre-commit

**Before opening a PR, install the pre-commit hooks once and run them.** The repo uses `pre-commit` (black for Python, clang-format for C++); PRs are expected to be hook-clean.

```bash
pip install pre-commit
pre-commit install                 # install the git hooks (run once per clone)

# run on the files you changed
pre-commit run --files <file1.py> <file2.py>
# or check everything
pre-commit run --all-files
```

You can also format a single file directly:

```bash
black <file>.py
# clang-format -i <file>.cpp   # for C++
```

Reminder: run `pre-commit run --all-files` (or at least on your changed files) as the **last step before pushing** — an unformatted diff will fail CI/review.

## PR expectations

1. Fork and open the PR against `main`.
2. New code that should be tested comes with tests (see above).
3. Every PR needs passing tests and at least one review.
4. Include **perf evidence** for anything performance-sensitive — a self-contained, reproducible benchmark. Use `Skill("mlx-vlm-skills:benchmarking")` for the fork-vs-main table format.
5. Keep the change scoped and opt-in; don't regress existing checkpoints.

## Routing

- Adding a model → `Skill("mlx-vlm-skills:add-new-model")`.
- Converting/quantizing weights → `Skill("mlx-vlm-skills:convert-quantize")`.
- Perf numbers for the PR → `Skill("mlx-vlm-skills:benchmarking")`.
- Filing a bug found while contributing → `Skill("mlx-vlm-skills:reproducible-github-issues")`.

Versions

RepositoryScoreLicence
This page · blaizzy/mlx-vlm100MIT
butterbase-ai/butterbase-skills100MIT
cloudflare/cloudflare-docs100CC-BY-4.0
emmgeede/gridselect100MIT
Jeff-Kazzee/github-skills100MIT
googlecloudplatform/race-condition100Apache-2.0
Dqz00116/skill-lib100MIT
iowarp/clio-core84BSD-3-Clause

Database snapshot: 13.11.2026 · package version 6cbf32c7e7d6 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100c-code-style
    Write, edit, or review C (and C-compatible header) code according to C coding style rules, then check and run clang-format to enforce formatting. Trigger on "write C code", "edit a .c/.h file", "review C code style", "format C code", "run clang-format", "check clang-format",…
  • 100black-to-ruff-format
    Migrate Python formatting from black to ruff-format. Use when psf/black is in .pre-commit-config.yaml or [tool.black] exists in pyproject.toml.
  • 100reproducible-github-issues
    Use this skill when the user wants to create, improve, or triage a reproducible GitHub issue for MLX-VLM, including bug reports from CLI inference, server inference, model loading, processors, media inputs, dependency setup, crashes, wrong outputs, or performance regressions.
  • 100hf-cache-models
    Use this skill when the user wants to list, inspect, or report cached, custom, or loaded MLX-VLM models through the server's model discovery endpoint.
  • 100cpp-quality
    C++ static analysis and formatting tooling: clang-tidy, clang-format, cppcheck, include-what-you-use (IWYU), and CI integration patterns. USE WHEN: user mentions "clang-tidy", "clang-format", "cppcheck", "iwyu", "include-what-you-use", ".clang-tidy", ".clang-format", "C++ static…
  • 100mlx-vlm
    Runs and fine-tunes vision language models (image, audio and video plus text) locally on Apple Silicon Macs with MLX, from a CLI, a Python API or an OpenAI-compatible server. Use when installing mlx-vlm, describing or extracting text from images with a local model, batch…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.