ZLS Integration Skill Skill

ZLS Integration Skill

Zig Language Server (ZLS) provides IDE features for Zig development. This skill covers installation, configuration, build-on-save diagnostics, and troubleshooting.

Quick Reference

| Feature | ZLS Support | Notes | |---------|-------------|-------| | Autocomplete | ✓ Full | Includes comptime-aware completion | | Goto Definition | ✓ Full | Cross-file navigation | | Find References | ✓ Full | All usages in workspace | | Hover Documentation | ✓ Full | Inline docs from source | | Diagnostics | ⚡ Parser-level | Semantic via build-on-save | | Rename Symbol | ✓ Full | Safe refactoring | | Code Actions | ✓ Partial | Fix imports, remove unused | | Formatting | ✓ Full | Uses zig fmt |

Installation

Via Package Manager (Recommended)

# macOS (Homebrew)
brew install zls

# Nix/Flox
flox install zls

# Arch Linux
pacman -S zls

# From source (any platform)
git clone https://github.com/zigtools/zls
cd zls
zig build -Doptimize=ReleaseSafe

Version Compatibility

| Zig Version | ZLS Version | Notes | |-------------|-------------|-------| | 0.15.x | 0.15.x | Current stable | | 0.14.x | 0.14.x | Previous stable | | 0.13.x | 0.13.x | Legacy | | master | master | Build from source |

Always match ZLS version to Zig version.

Configuration

zls.json Location

~/.config/zls.json           # Linux/macOS
%APPDATA%\zls.json           # Windows
<project>/.zls.json          # Project-specific

Essential Configuration

{
  "zig_exe_path": "/path/to/zig",
  "enable_autofix": true,
  "enable_import_access": true,
  "highlight_global_var_declarations": true,
  "warn_style": true,
  "enable_build_on_save": true,
  "build_on_save_step": "check"
}

Build-On-Save Diagnostics

ZLS can run your build script on save to catch semantic errors (type mismatches, wrong argument counts) that parser-level analysis misses.

Step 1: Add Check Step to build.zig

// build.zig
pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const exe = b.addExecutable(.{
        .name = "myapp",
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    b.installArtifact(exe);

    // ZLS check step - runs on save
    const check = b.addExecutable(.{
        .name = "myapp",
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    
    const check_step = b.step("check", "Check compilation (for ZLS)");
    check_step.dependOn(&check.step);
}

Step 2: Configure ZLS

{
  "enable_build_on_save": true,
  "build_on_save_step": "check"
}

Step 3: Editor Setup

VS Code (zls extension):

// settings.json
{
  "zig.zls.path": "/path/to/zls",
  "zig.zls.enableBuildOnSave": true
}

Neovim (nvim-lspconfig):

require('lspconfig').zls.setup({
  settings = {
    zls = {
      enable_build_on_save = true,
      build_on_save_step = "check"
    }
  }
})

Emacs (lsp-mode):

(setq lsp-zig-zls-executable "/path/to/zls")
(setq lsp-zig-enable-build-on-save t)

Troubleshooting

No Diagnostics Appearing

Verify ZLS is running: pgrep -l zls
Check ZLS log: ~/.cache/zls/zls.log
Ensure Zig version matches: zig version vs zls --version
Test build manually: zig build check

Slow Completions

{
  "skip_std_references": true,
  "prefer_ast_check_as_child_process": true
}

Import Resolution Failures

{
  "enable_import_access": true,
  "additional_module_paths": ["deps/", "vendor/"]
}

Build-On-Save Not Working

Verify check step exists in build.zig
Run zig build check manually
Check ZLS config: enable_build_on_save: true
Restart language server

GF(3) Integration

ZLS diagnostics map to triadic workflow:

| Diagnostic Type | Trit | Action | |-----------------|------|--------| | Error (red) | -1 | Must fix before build | | Warning (yellow) | 0 | Review, may ignore | | Hint (blue) | +1 | Optimization opportunity |

Conservation: errors + warnings + hints → 0 as code improves.

Editor Integration Matrix

| Editor | Plugin | Config Path | |--------|--------|-------------| | VS Code | zls (extension) | .vscode/settings.json | | Neovim | nvim-lspconfig | init.lua or lsp.lua | | Helix | Built-in | languages.toml | | Emacs | lsp-mode + lsp-zig | init.el | | Sublime | LSP-zig | *.sublime-settings | | Vim | vim-lsp or coc.nvim | .vimrc or coc-settings.json |

Related Skills

zig-programming - Core Zig language and stdlib
zig-async-io - Async/concurrent patterns (0.16.0+)
tree-sitter - AST-based code analysis

Resources

Scientific Skill Interleaving

This skill connects to the K-Dense-AI/claude-scientific-skills ecosystem:

Graph Theory

networkx [○] via bicomodule
- Universal graph hub

Bibliography References

general: 734 citations in bib.duckdb

Cat# Integration

This skill maps to Cat# = Comod(P) as a bicomodule in the equipment structure:

Trit: 0 (ERGODIC)
Home: Prof
Poly Op: ⊗
Kan Role: Adj
Color: #26D826

GF(3) Naturality

The skill participates in triads satisfying:

(-1) + (0) + (+1) ≡ 0 (mod 3)

This ensures compositional coherence in the Cat# equipment structure.

Agent Skills: ZLS Integration Skill

Install this agent skill to your local

Skill Files