Skip to content
Skills Library
Programming · Building & coding

zig-guide

/zig-guide

Zig language guardrails, patterns, and best practices for AI-assisted development. Use when working with Zig files (.zig), build.zig, or when the user mentions Zig. Provides comptime patterns, allocator conventions, C interop guidelines, and testing standards specific to this project's coding standards.

Repository
samuel ↗
Licence
MIT
Last repository change
29.04.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
5
Deprecation

No signals detected. Repository changed on 29.04.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Zig language guardrails, patterns, and best practices for AI-assisted development. Use when working with Zig files (.zig), build.zig, or when the user mentions Zig. Provides comptime patterns, allocator conventions, C interop guidelines, and testing standards specific to this project's coding standards.

Original author description

Zig language guardrails, patterns, and best practices for AI-assisted development. Use when working with Zig files (.zig), build.zig, or when the user mentions Zig. Provides comptime patterns, allocator conventions, C interop guidelines, and testing standards specific to this project's coding standards.

How it works

  1. Core Principles
  2. Guardrails
  3. Key Patterns
  4. Testing
  5. Tooling
  6. C Interop
  7. References
  8. External References
Original SKILL.md headings · 200 lines, 976 words
SKILL.md preview
---
name: zig-guide
description: |
  Zig language guardrails, patterns, and best practices for AI-assisted development.
  Use when working with Zig files (.zig), build.zig, or when the user mentions Zig.
  Provides comptime patterns, allocator conventions, C interop guidelines,
  and testing standards specific to this project's coding standards.
license: MIT
metadata:
  author: samuel
  version: "1.0"
  category: language
  language: zig
  extensions: ".zig"
---

# Zig Guide

> Applies to: Zig 0.13+, Systems Programming, CLIs, Embedded, Game Engines, C/C++ Replacement

## Core Principles

1. **Explicit Over Implicit**: No hidden control flow, no hidden allocations, no operator overloading, no implicit conversions
2. **Allocator Passing**: Every function that allocates receives an `std.mem.Allocator` as a parameter; never use a global allocator
3. **Errors Are Values**: Use error unions (`!`) with `try`, `catch`, and `errdefer`; never silently discard errors
4. **Comptime Over Runtime**: Move computation to compile time with `comptime`; use it for generics, validation, and code generation
5. **Safety With Escape Hatches**: Keep runtime safety enabled by default; disable only in measured hot paths with a justifying comment

## Guardrails

### Code Style

- Run `zig fmt` before every commit (non-negotiable)
- `camelCase` functions/variables, `PascalCase` types/structs/enums, `SCREAMING_SNAKE_CASE` module constants
- Prefer `snake_case` for file names (`my_module.zig`)
- Discard unused values explicitly: `_ = value;` (no `_` prefix naming)
- Prefer `const` over `var` everywhere; mutability requires justification
- All public declarations (`pub fn`, `pub const`) must have a doc comment (`///`)

### Memory and Allocators

- Every function that heap-allocates must accept an `std.mem.Allocator` parameter
- Always pair `alloc`/`free` with `defer` or `errdefer` at the call site
- Use `std.heap.ArenaAllocator` for batch allocations freed together
- Use `std.heap.GeneralPurposeAllocator` in debug builds (detects leaks, double-free)
- Never store an allocator in a struct unless the struct owns long-lived memory
- Prefer stack allocation (`var buf: [256]u8 = undefined;`) for small, bounded buffers
- Slices (`[]T`, `[]const T`) over raw pointers (`[*]T`) whenever possible

### Error Handling

- Return error unions (`!T`) for all fallible operations
- Use `try` to propagate; use `catch` only where you can handle or log meaningfully
- Use `errdefer` to clean up resources on error paths
- Define domain-specific error sets; avoid `anyerror` except at top-level boundaries
- Never ignore errors: `_ = fallibleFn();` is forbidden outside tests

```zig
const ConfigError = error{ FileNotFound, InvalidFormat, MissingField };

fn loadConfig(allocator: std.mem.Allocator, path: []const u8) ConfigError!Config {
    const file = std.fs.cwd().openFile(path, .{}) catch return error.FileNotFound;
    defer file.close();
    // parse and return ...
}
```

### Comptime

- Use `comptime` parameters for generics instead of runtime polymorphism
- Use `@typeInfo` and `@Type` for type introspection at compile time
- Use `@compileError` to produce clear messages for invalid type combinations
- Prefer `inline for` only when the loop count is comptime-known and small

```zig
fn max(comptime T: type, a: T, b: T) T {
    return if (a > b) a else b;
}

fn ensureUnsigned(comptime T: type) void {
    if (@typeInfo(T) != .int or @typeInfo(T).int.signedness == .signed)
        @compileError("expected unsigned integer type");
}
```

### Safety

- Keep runtime safety enabled in debug and test builds
- Validate all external inputs (file I/O, network, FFI boundaries)
- Use `std.math.add` / `std.math.mul` for checked arithmetic; sentinel slices (`[:0]const u8`) for C strings
- Avoid `@ptrCast` and `@intFromPtr` unless interfacing with C; justify each use

## Key Patterns

### Optionals

```zig
fn findUser(users: []const User, id: u64) ?*const User {
    for (users) |*user| {
        if (user.id == id) return user;
    }
    return null;
}

const user = findUser(users, 42) orelse return error.UserNotFound;

if (findUser(users, 42)) |u| {
    std.debug.print("Found: {s}\n", .{u.name});
}
```

### Defer and Errdefer

```zig
fn createConnection(allocator: std.mem.Allocator, host: []const u8) !*Connection {
    const conn = try allocator.create(Connection);
    errdefer allocator.destroy(conn); // only runs on error return

    conn.* = .{ .socket = try std.net.tcpConnectToHost(allocator, host, 8080), .allocator = allocator };
    errdefer conn.socket.close();

    try conn.performHandshake();
    return conn;
}
```

### Slices vs Arrays

```zig
const fixed: [4]u8 = .{ 1, 2, 3, 4 };          // fixed-size array (stack)
const c_str: [:0]const u8 = "hello";             // sentinel-terminated (C compat)

fn sum(values: []const u32) u64 {                // slice (preferred for params)
    var total: u64 = 0;
    for (values) |v| total += v;
    return total;
}
```

### Packed and Extern Structs

```zig
const StatusRegister = packed struct {
    carry: u1, zero: u1, irq_disable: u1, decimal: u1,
    brk: u1, _reserved: u1, overflow: u1, negative: u1,
};
const CFileHeader = extern struct { magic: u32, version: u16, flags: u16, size: u64 };
```

## Testing

```zig
const testing = @import("std").testing;

test "add returns correct sum" {
    try testing.expectEqual(@as(i32, 5), add(2, 3));
}

test "string list detects leaks via testing allocator" {
    var list = StringList.init(testing.allocator); // leak detection built-in
    defer list.deinit();
    try list.add("hello");
    try testing.expectEqual(@as(usize, 1), list.items.items.len);
}

test "readFileContents returns error for missing file" {
    try testing.expectError(error.FileNotFound, readFileContents(testing.allocator, "/nonexistent"));
}
```

### Testing Standards

- Test names describe behavior: `test "user creation fails with empty name"`
- Unit tests live in `test` blocks inside the same `.zig` file
- Integration tests go in `tests/` directory
- Use `std.testing.allocator` -- it detects memory leaks automatically
- Key assertions: `expectEqual`, `expectError`, `expectEqualStrings`, `expectEqualSlices`
- Coverage target: >80% for library code, >60% for application code

## Tooling

```bash
zig build              # Build (uses build.zig)
zig build test         # Run all tests
zig build run          # Build and run
zig fmt src/           # Format all source files
zig test src/main.zig  # Test a single file
zig build -Doptimize=ReleaseSafe   # Optimized with safety
zig build -Doptimize=ReleaseFast   # Maximum performance
```

See patterns.md for a build.zig template.

## C Interop

- Use `@cImport` / `@cInclude` for C headers (not manual extern declarations)
- Use `[*c]T` only at FFI boundary; convert to `[]T` or `?*T` immediately
- Use `std.mem.span` to convert `[*:0]const u8` (C string) to Zig slice
- Always call `exe.linkLibC()` in build.zig when using libc
- Validate all values received from C before using in safe Zig code

## References

For full implementation examples, see:

- [references/patterns.md](references/patterns.md) -- Arena allocator, GPA leak detection, comptime generics, comptime interface validation, C library wrapper (SQLite), sentinel string conversion, tagged union state machines, errdefer chains, build.zig template

## External References

- [Zig Language Reference](https://ziglang.org/documentation/master/)
- [Zig Standard Library Docs](https://ziglang.org/documentation/master/std/)
- [Zig Learn](https://ziglearn.org/)
- [Zig by Example](https://zig-by-example.github.io/)
- [Zig Cookbook](https://cookbook.ziglang.cc/)
Files in this package (2)
  • SKILL.md 8 KB
  • references/patterns.md 7 KB

Versions

The database has no other skills named zig-guide.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 6ed37d3a9489 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100zig-project
    Modern Zig project architecture guide. Use when creating Zig projects (systems programming, CLI tools, game dev, high-performance services). Covers explicit allocators, comptime, error handling, and build system.
  • 100zig-testing
    Zig testing skill for writing and running tests. Use when using zig build test, writing comptime tests, using test filters, working with test allocators to detect leaks, or using Zig's built-in fuzz testing (0.14+). Activates on queries about Zig tests, zig test, zig build test,…
  • 95zig-best-practices
    Provides Zig patterns for type-first development with tagged unions, explicit error sets, comptime validation, and memory management. Must use when reading or writing Zig files.
  • 96zig-best-practices
    Use when reading or writing Zig files (.zig, build.zig, build.zig.zon).
  • 100language
    Guide for Zig core language features. Use when writing Zig code with comptime, error handling, data types, slices, optionals, defer, or following Zig idioms.
  • 100zig-testing
    Use when writing or running Zig tests: test blocks, zig test, filters, std.testing assertions, the leak-detecting allocator, comptime tests, or the fuzzer. Not for build.zig: use zig-build-system.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.