---
name: zig-ecosystem-tooling-gaps
description: Current Zig ecosystem and tooling gap assessment workflow for coding agents as of 2026-05-13. Use when evaluating Zig adoption risk, dependency hygiene, package management, ZLS/editor behavior, compiler or stdlib regressions, pre-1.0 API churn, cross-platform support tiers, unofficial package indexes, toolchain pinning, CI matrices, or mitigation plans for Zig 0.15/0.16-era ecosystem gaps.
---

# Zig Ecosystem Tooling Gaps

## Operating Mode

Use this skill to separate real ecosystem risk from stale folklore. Start with the exact local baseline:

```bash
zig version
test -f build.zig.zon && sed -n '1,160p' build.zig.zon
test -f .zigversion && cat .zigversion
command -v zls >/dev/null && zls --version || true
```

As of 2026-05-13, Zig `0.16.0` is the latest tagged release and `0.17.0-dev` builds are available. Orca-style repos may still pin `0.15.2`; treat the repo pin as binding unless the task is an upgrade.

## Risk Model

- Zig is pre-1.0. Language, stdlib, build APIs, package metadata, compiler behavior, and linker behavior can change across minor releases.
- Non-trivial projects may encounter compiler bugs, miscompilations, regressions, or target-specific gaps. Reduce and verify before blaming project code.
- Ecosystem maturity varies by domain. Do not assume Rust/Go-level package depth, registry conventions, IDE support, or long-term API stability.
- Current docs and examples on the web often target older Zig releases. Verify examples against the project-pinned Zig before applying them.

## Package Management Gaps

- Zig has a built-in package manager and `build.zig.zon`, but no official central package repository.
- Treat `build.zig.zon` as the source of truth for dependency identity, URLs, hashes, fingerprints, and package `paths`.
- Prefer upstream repositories, signed releases where available, exact hashes, and tracked provenance over unofficial package indexes.
- Use `zig fetch` and Zig-suggested hashes/fingerprints instead of hand-written values.
- Keep dependency cache output such as `zig-pkg/` out of source unless the repo intentionally vendors it.
- For temporary dependency forks on Zig `0.16.0+`, prefer `zig build --fork=/path/to/clone` over editing fetched cache contents.

## ZLS And Editor Tooling

- Keep Zig and ZLS in sync. Tagged ZLS releases target matching Zig releases; ZLS master targets Zig master.
- ZLS is useful but not authoritative. Compiler/test output wins over editor diagnostics.
- If editor behavior is wrong, capture `zig version`, `zls --version`, editor config, and whether the project has a `check` step.
- Prefer a `zig build check` step for build-on-save diagnostics. It should compile/analyze without installing artifacts.
- ZLS schema/config options change over time; use version-matched schema docs for tagged releases.

## Version Drift Hotspots

For 0.15.x to 0.16.x work, inspect:

- `std.Io`, filesystem, process, networking, and environment APIs.
- `@cImport` moving toward build-system C translation.
- `@Type` replacement by specific type-creating builtins.
- Managed-to-unmanaged container migration.
- `heap.ArenaAllocator`, removed thread-safe allocator wrappers, and allocator naming/defaults.
- Package metadata strictness, local overrides, project-local `zig-pkg`, and test-timeout/build flags.
- Fuzzer interface changes and release-mode behavior.

Do not mix 0.16 examples into 0.15 implementation without labeling them as migration-only.

## Cross-Platform Reality Check

- Use Zig's current target/tier table before claiming platform support.
- Treat Tier 1 and Tier 2 as stronger signals, but still verify the project.
- Treat Tier 3, Tier 4, and additional platforms as requiring explicit compile, link, and runtime proof for the project.
- For Zig `0.16.0`, note current minimums before support claims: Linux 5.10, macOS 13.0, Windows 10, FreeBSD 14.0, NetBSD 10.1, OpenBSD 7.8.
- Cross-compilation proves code generation/linking for a target, not runtime semantics or OS integration.

## Triage Playbook

When something breaks:

1. Record exact command, target, optimize mode, Zig version, ZLS version if relevant, and host OS.
2. Reproduce with the project-pinned Zig.
3. Try latest stable Zig only to classify drift, not to redefine the project contract.
4. Check dependency versions and `build.zig.zon` hashes/fingerprints.
5. Minimize the failure to a single source file or tiny build step.
6. Search official Zig issue trackers/release notes for matching bugs, miscompilations, regressions, and breaking changes.
7. Prefer small compatibility shims and documented migration notes over broad rewrites.

## Mitigation Checklist

- Pin Zig in docs, CI, scripts, and `build.zig.zon.minimum_zig_version`.
- Add CI for native build/test plus important cross-target compile lanes.
- Keep a `check` step for fast compiler diagnostics and ZLS build-on-save.
- Maintain migration notes per Zig release.
- Vendor or fork critical dependencies only with explicit provenance and update workflow.
- Gate upgrades with `zig build`, `zig build test`, package-surface checks, target builds, and CLI/editor sanity checks.
- Report ecosystem limitations honestly in release notes and customer-facing docs.

## Source Refresh

Refresh before current-state claims:

- `https://ziglang.org/download/`
- `https://ziglang.org/download/0.16.0/release-notes.html`
- `https://ziglang.org/documentation/0.16.0/`
- `https://ziglang.org/learn/getting-started/`
- `https://zigtools.org/zls/releases/`
- `https://zigtools.org/zls/releases/0.16.0/`
- `https://zigtools.org/zls/guides/build-on-save/`