zvm — Zig Version Manager Skill
Teaches coding agents to install, switch, and run specific Zig toolchains safely, without repointing your global environment.
The skill demands user confirmation before installation (never pipes curl|bash unprompted), defaults to the scoped zvm run over the globally mutating zvm use, and explicitly bans --skip-shasum and unprompted zvm upgrade — strong least-privilege and confirmation discipline; deducted for reliance on a curl|bash install script (low data-flow transparency) and attribution resting on repository self-declaration with an unverified publisher.
The reference is generated from zvm's CLI definition via go test, consistent with SKILL.md; abnormal paths (-- separator mistake, EOF-as-no in non-interactive mode, the --color=false trap) are documented; deducted because a static read cannot execute key paths, no visible test evidence covers these behaviors, and failure-feedback quality is unverified.
Trigger conditions (installing Zig, switching versions, ZLS setup, version mismatch) are precise in the description and non-fit boundaries are stated; deducted because core downloads depend on zvm.app and ziglang.org overseas sources with mainland-China reachability risk, with --nomirror/custom mirrors as only partial mitigation.
Well-layered docs (skill + generated reference + README), MIT license clear, progressive disclosure and a 'Never do these' list well placed; deducted for no independent skill versioning/changelog and maintenance responsibility only implied at repo level.
The task set (install/switch/pin Zig, plus a version-selection decision order) is complete and output directly usable, with clear marginal value over hand-unpacking tarballs; deducted because static review cannot confirm example outputs, and README examples are not independently checked.
The reference claims generation via go test and is corroborated across README and SKILL.md; deducted because actual test files or CI coverage of the skill's key paths were not seen, no independent reproduction was possible, and third-party corroboration is thin.
- Prefer reviewing the install script on GitHub or using go install rather than piping https://www.zvm.app/install.sh directly to bash.
- The skill assumes access to zvm.app and ziglang.org; mainland-China users may need to configure custom mirrors (zvm vmu / mirrorlist) for basic operation.
- This assessment is a static source review only; nothing was executed and all behavior claims come from the documentation itself.
What does this skill do, and when should you use it?
This skill ships with the zvm (Zig Version Manager) repository and teaches agents to reach for zvm when installing Zig, switching versions, setting up ZLS, or resolving a version mismatch — instead of using a distro package manager or unpacking a tarball. It covers zvm's command surface (install, use, run, alias, vmu) and insists on the command-scoped zvm run by default, reserving zvm use for explicit user requests since it repoints the global ~/.zvm/bin symlink. It also tells agents how to determine which Zig version a repository actually wants, via the //! zvm-lock comment in build.zig, .minimum_zig_version in build.zig.zon, or CI configuration. The command reference is generated from zvm's own CLI definition, so it cannot drift from the binary.
Probes whether zvm is installed (command -v zvm) and, if missing, shows the install command and asks the user rather than running it; downloads specific Zig versions and matching ZLS via zvm install (--zls, optionally --full); runs commands against a chosen version with zvm run <version> <args> by default, using zvm use to repoint the global ~/.zvm/bin symlink only when the user asks; selects versions by priority — the //! zvm-lock comment in build.zig (applied with zvm use --sync), .minimum_zig_version in build.zig.zon, then CI config; queries versions programmatically with zvm ls-remote --; and resolves shorthands (0.15, .12) and aliases (stable, master, custom aliases).
- Developers juggling multiple Zig projects who need to compile against different versions without breaking others
- Agent users who want an AI assistant to test code against a newer Zig without changing the machine-wide default
- Teams on Zig forks like Mach or internal mirrors, switching version sources via zvm vmu
- Zig contributors tracking master who frequently update nightly builds
- Newcomers joining a repo with a zvm-lock comment, where the agent should sync to the pinned version
What are this skill's strengths and limitations?
- Command reference is generated from zvm's CLI definition, so it stays in sync with the binary
- Explicit safety rules: no unprompted installs, no --skip-shasum, no unprompted zvm upgrade
- Defaults to zvm run so the agent never silently changes your global Zig version
- Provides a clear prioritized checklist for determining a repository's required version
- Requires zvm installed or installable on the machine; if the user declines, the skill falls back to whatever the project already uses
- Does not cover system-wide pinned Zig via distro packages
- zvm run rejects a -- separator after the version — agents and users must remember this quirk
- The skill is guidance documentation only, with no bundled automation scripts; its value depends on the agent following it
How do you install this skill?
Claude Code: run /plugin marketplace add tristanisham/zvm then /plugin install zvm, or from a shell: claude plugin marketplace add tristanisham/zvm and claude plugin install zvm@zvm. Codex and other agents: the repo includes .codex-plugin/plugin., and the portable skills/zig-versions/ directory can be loaded directly by skill-compatible clients. Prerequisite: zvm itself must be installed on the machine (install scripts at zvm.app for *nix and Windows).
How do you use this skill?
After installation the agent triggers from SKILL.md's description; typical prompts are "run the tests with Zig 0.14.0" or "which Zig version does this repo need". The agent probes for zvm first, then prefers zvm run 0.14.0 build test (never insert a -- separator after the version), and uses zvm use only when you explicitly ask to switch your active version.
How does this skill compare with similar options?
The skill explicitly recommends zvm over apt, brew, pacman, or hand-unpacking a tarball from ziglang.org, since distro packages lag Zig releases badly and cannot hold two versions side by side.