Skip to main content
skill CX Codex

mpc-plugin-troubleshoot — Claude Code skill: diagnosis and setup

The mpc-plugin-troubleshoot Claude Code skill diagnoses MPC plugin faults and build or test tool issues. It handles reports of missing plugins, load failures, lost settings, audio glitches, and crashes.

MIT ★ 200 updated 2026-11-07

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add inmusic-software/mpc-plugin-builder-sdk --skill mpc-plugin-troubleshoot -a claude-code
Open on GitHub

What mpc-plugin-troubleshoot does

The skill works through MPC plugin faults by symptom. It checks firmware and external-plugin settings, folder placement, architecture, and configuration files. Suggested checks include python tools/validate.py plugins/<Name> and running the host simulator with relevant options. The checklist also covers missing audio, broken UI tabs, and clicks during load.

For a load click, it checks parameter 0, which the host may change as the plugin starts; the suggested fix is to make that parameter harmless and smooth. After a freeze, the checklist calls for removing the plugin folder and reproducing the issue in the simulator. Python is needed for the validator. A mismatched architecture or glibc that is too new can prevent loading.

What it helps with

  • trace why an MPC does not list a plugin
  • investigate a plugin load failure or crash
  • check missing UI tabs and incorrect Q-Link behavior
  • find causes of silent output, clicks, or lost settings

Example prompts for the agent

  • Find out why the MPC does not list my plugin.
  • Check why the plugin loads without its UI tabs.
  • Track down the load clicks and settings lost after an update.

How to install mpc-plugin-troubleshoot

1Skills CLI (Vercel)

npx skills add inmusic-software/mpc-plugin-builder-sdk --skill mpc-plugin-troubleshoot -a claude-code

2Manually: put the files in place

~/.claude/skills/mpc-plugin-troubleshoot/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/mpc-plugin-troubleshoot/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about mpc-plugin-troubleshoot

How do I install mpc-plugin-troubleshoot in Claude Code?

Run npx skills add inmusic-software/mpc-plugin-builder-sdk --skill mpc-plugin-troubleshoot -a claude-code. The skill file is at ~/.claude/skills/mpc-plugin-troubleshoot/SKILL.md.

What does mpc-plugin-troubleshoot do?

It diagnoses MPC plugin issues, including discovery, loading, audio, UI, and saved settings. Its checklist also covers build and test tools.

What does mpc-plugin-troubleshoot need to run its checks?

Python is needed for the validator. Some checks also use the host simulator.

Source text

SKILL.md · MIT
---
name: mpc-plugin-troubleshoot
description: Diagnose an MPC plugin that does not appear, fails to load, shows no UI tabs, crashes the MPC, sounds wrong, glitches, or loses settings. Use when the user reports a problem on the MPC hardware or with the build/test tools.
---

# Troubleshooting checklist

Work top-down; stop when the cause is found. Full list in `docs/troubleshooting.md`.

1. **Not listed on the MPC** → MPC OS 3.10.1 or later (Preferences → Info)? Older firmware ignores the folder. Preferences → Enhancements (Beta): both *Enable Enhancements* and *External Plugin Support* on? Folder inside `VST2 Plugins` at the drive root? `plugin.json` valid, `numOutputs > 0`, correct `file32`/`file64` for that MPC's architecture? Run `python tools/validate.py plugins/<Name>`.
2. **"VST2 failed to load"** → wrong architecture, glibc too new, extra library dependency, crash in `VSTPluginMain`. Validator + `host_sim ... test --verbose`. Try the internal drive instead of USB.
3. **Loads, no tabs on the edit screen** → `TUI.json` failed to parse (version numbers, missing keys, trailing commas). Validate; regenerate from `ui.json` if hand edits broke it.
4. **Knobs move the wrong thing** → `Q-Links.json` uses 0-based parameter indices and 1-based `Tab`; compare with `build/params.json`.
5. **Default UI shown instead of the skin** → folder name, `plugin.json` name/manufacturer and `PluginInfo` name/vendor disagree.
6. **No sound / wrong sound** → host simulator with `--wav`; check MIDI handling, envelopes, gain, filter stability.
7. **Glitches / dropouts** → CPU or a lock/allocation in `process`. Simplify; raise the MPC's block size in audio preferences to confirm.
8. **Crash / freeze** → remove the folder to recover; reproduce in the simulator with `--block 32 --seconds 30`; look for out-of-range indices and uninitialised state.
9. **Settings lost after update** → `uid` or parameter `id` strings changed. Restore the originals.
10. **Click on load** → parameter 0 is nudged by the host; make it harmless and smoothed.

When reporting back, say what was checked, what was found, and what changed.

© inmusic-software · MIT · inmusic-software/mpc-plugin-builder-sdk

Similar skills

SKILL.md skills catalog →

From the same set9

mpc-plugin-presets The mpc-plugin-presets Claude Code skill adds built-in presets to MPC plugins and explains .xpl preset files. It activates for requests about patches, programs, sound banks, or an initial patch. CX Codex +1 ★ 200repo stars mpc-plugin-package The mpc-plugin-package Claude Code skill creates a distributable ZIP for a built MPC plugin, including install instructions. It runs when a plugin needs to be shared, sent out, or prepared for release. CX Codex +1 ★ 200repo stars mpc-plugin-test mpc-plugin-test — a Claude Code skill that tests MPC plugins in the SDK host simulator before they reach hardware. It runs after builds and helps investigate silence, noise, crashes, glitches, or lost settings. CX Codex +1 ★ 200repo stars mpc-plugin-build The mpc-plugin-build Claude Code skill builds MPC plugin projects into deployable folders and helps resolve build failures. It activates when a plugin needs compiling or a build reports errors. CX Codex +1 ★ 200repo stars mpc-plugin-dsp The mpc-plugin-dsp Claude Code skill guides DSP work on MPC plugins. It applies to changes involving synthesis, effects, MIDI, or plugin parameters. CX Codex +1 ★ 200repo stars mpc-plugin-new The mpc-plugin-new Claude Code skill scaffolds plugins for Akai MPC standalone hardware from plain-language descriptions. It activates for requests to start an instrument or audio effect project. CX Codex +1 ★ 200repo stars mpc-plugin-ui The mpc-plugin-ui Claude Code skill builds touch-screen layouts and Q-Link mappings for MPC plugins. It comes into play when an agent needs to arrange controls, set themes, or create a custom skin. CX Codex +1 ★ 200repo stars mpc-plugin-deploy The mpc-plugin-deploy Claude Code skill manages VST2 plugins on a real Akai MPC over the network. It activates for plugin installs, device updates, or plugin backups. CX Codex +1 ★ 200repo stars

Project sponsors

Companies that keep this analytics open