# Reproducible Github Issues

Use this skill when the user wants to create, improve, or triage a reproducible GitHub...

- Repository: https://github.com/Blaizzy/mlx-vlm (5707 stars)
- Category: Git and review
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add Blaizzy/mlx-vlm --skill reproducible-github-issues -g -a claude-code -y`
Codex: `npx skills add Blaizzy/mlx-vlm --skill reproducible-github-issues -g -a codex -y`
Cursor: `npx skills add Blaizzy/mlx-vlm --skill reproducible-github-issues -g -a cursor -y`
Gemini CLI: `npx skills add Blaizzy/mlx-vlm --skill reproducible-github-issues -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add Blaizzy/mlx-vlm`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Reproducible GitHub Issues

Use this workflow to turn a failure into a concise, actionable MLX-VLM issue. Do not open a GitHub issue unless the user explicitly asks; otherwise produce issue-ready Markdown.

## Required Information

Collect or infer:

- MLX-VLM version or git commit.
- Install method: PyPI, editable checkout, branch, or wheel.
- Python version, OS version, machine/chip, and whether MLX Metal or MLX CUDA is in use.
- Exact model ID or local path.
- Whether the model is from Hugging Face cache, a local conversion, or a custom checkpoint.
- Exact `uv run` CLI command or server startup command.
- Exact request body for server issues.
- Input media facts: image dimensions, audio duration/sample rate, video duration/frame count, and whether the input can be shared.
- Expected behavior, actual behavior, and full error/traceback.

## Collect the Environment Automatically

Instead of hand-filling versions, run and paste the output into the Environment section:

```bash
uv run python - <<'PY'
import platform, mlx.core as mx
try:
    import mlx_vlm
    v = getattr(mlx_vlm, "__version__", "unknown")
except Exception as e:
    v = f"import failed: {e}"
print("mlx-vlm:", v)
print("mlx:", mx.__version__, "| default device:", mx.default_device())
print("python:", platform.python_version(), "| platform:", platform.platform())
PY
```

## Repro Minimization

1. Reduce to the smallest command or request that still fails.
2. Remove private paths, tokens, and unrelated environment variables.
3. Prefer `curl` over client SDKs for server repros.
4. Prefer one image/audio/video file before multi-input repros.
5. Use small public media or synthetic inputs when possible.
6. State whether the bug reproduces with a public model or only a private/local checkpoint.

## Issue Template

````markdown
### Summary

<One sentence describing the failure.>

### Environment

- MLX-VLM:
- Python:
- OS:
- Hardware:
- Install method:

### Model

The rest: https://github.com/Blaizzy/mlx-vlm/blob/HEAD/skills/skills/reproducible-github-issues/SKILL.md