Agent skill

zls-integration

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/zls-integration

SKILL.md

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)

bash
# 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

json
{
  "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

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

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

Step 3: Editor Setup

VS Code (zls extension):

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

Neovim (nvim-lspconfig):

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

Emacs (lsp-mode):

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

Troubleshooting

No Diagnostics Appearing

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

Slow Completions

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

Import Resolution Failures

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

Build-On-Save Not Working

  1. Verify check step exists in build.zig
  2. Run zig build check manually
  3. Check ZLS config: enable_build_on_save: true
  4. 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.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results