# zig-016 Adopt this skill: https://proskills.md/skills/other/baskingspot-skills-eval-scaffold-agents-skills-zig-016 Page: https://proskills.md/skills/other/baskingspot-skills-eval-scaffold-agents-skills-zig-016 This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required. ## File: eval/scaffold/.agents/skills/zig-016/SKILL.md size: 14335 sha: 9a6f9d41f750239823039fdd7edd81116b49fef9 upstream: https://github.com/baskingspot/skills/blob/main/eval/scaffold/.agents/skills/zig-016/SKILL.md ````text --- name: zig-016 description: Write Zig 0.16 with tested primitives, testingx, and the baskingspot house style. Use when writing or reviewing Zig 0.16 code, before hand-rolling a container, parser, codec, flag loop, or IP type, when adding tests or benchmarks, or when choosing between std, a baskingspot library, and a new type. --- # Zig 0.16 Read [zig-0.16.md](references/zig-0.16.md) before the first Zig file. Training data covers 0.11 to 0.15, and 0.16 moved `main`, `Io`, the filesystem API, and the names of half of `std.mem`. Written cold, Zig drifts toward C: a struct holding a slice and a length, a `while` over `split` that parses as it scans, a bitset rebuilt from a `[4]u64`. Each of those is a **primitive** that already exists, with tests and measurements behind it. The work is to name the primitive before writing the type. ## Name it first Before writing a type or a parse loop, say what it is in one or two words. If the words name a data structure or a protocol, the primitive exists. Check in this order and stop at the first hit: 1. `std` in the pinned toolchain. `zig env` prints `.std_dir`, and a grep of that tree takes seconds. 2. `stdx`, a package of extensions to `std` that baskingspot publishes: the containers and parsers std does not have. Its [guide](https://baskingspot.dev/stdx/index.md) is one page and covers every module. 3. Your own type, with a comment naming what the first two lacked. ## Add the dependency The packages are how this is done here, so adding one is the default, not a favour to ask about. Add it, wire it in `build.zig`, and name it in the final message. Ask first only when the project is not yours to change. ```sh zig fetch --save git+https://github.com/baskingspot/stdx # before stdx v0.1.0 zig fetch --save https://baskingspot.dev/stdx/vX.Y.Z.tar.gz # a released package ``` A released package takes the site URL. Never the GitHub archive URL, and never a branch. ## Containers | About to write | Use | Why | | ------------------------------------------------ | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | A struct holding an array and a length | `stdx.buffer.Array(T, capacity)` | The capacity is in the type and the storage in the value. No allocator. | | The same over memory you already own | `stdx.buffer.Slice(T)` | Same methods. The capacity is the slice length. | | A buffer a transport refills and a parser drains | `stdx.buffer.Queue(T)` | Borrows storage. `rebase` compacts the consumed front. | | A list with no upper bound | `std.ArrayList(T)` | Unmanaged in 0.16; pass the allocator to each call. The managed one is `array_list.Managed`. | | A map with a fixed capacity | `stdx.bounded_array_hash_map.Auto(K, V, n)` | Insertion order, no allocator. | | A map that grows | `stdx.swiss.Auto(K, V)` | Swiss table, uses an allocator, order is not insertion order. | | Keys kept in sorted order | `stdx.btree.Auto(K, V)`, `stdx.btree.String(V)` | Uses an allocator. Iteration is in key order; `iteratorFrom` starts anywhere. | | A map keyed by a dense enum | `std.EnumMap(E, V)` | An array indexed by `@intFromEnum`. | | A constant lookup table | `stdx.static_map.Auto(K, V, .{ ... })` | Built at compile time; a duplicate key is a compile error. `std.StaticStringMap` for string keys. | | A set | `stdx.set.Auto(K, capacity)` | A map with no values, plus set algebra. | | A bitset | `std.bit_set` | | | A set of indices reused every pass | `stdx.bit_set.Scratch(capacity)` | Reset clears a validity map, not the dirty words. | | A cheap "have I seen this" test | `stdx.bloom.Auto(...)` | Reports false positives, never false negatives. | | One array per struct field | `std.MultiArrayList(T)` | Fixed length: `stdx.multi_array.Array`. Runtime length without an allocator: `stdx.multi_array.Buffer(T, capacity)`. | | The smallest or largest item first | `stdx.priority_queue.Custom(...)` | A binary heap with a fixed capacity. `std.PriorityQueue` allocates. | | A writer over an allocated buffer | `stdx.BoundedWriter` | Fails at a hard byte limit instead of growing. | | Buffered stderr and stdout | `stdx.stdio` | Streams that never return an error. | ## Parsing, encoding, and the rest | About to write | Use | Why | | ----------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------ | | An IPv4 address or a CIDR prefix | `stdx.net.Ip4`, `stdx.net.Prefix4` | std has no IPv4 type. These follow Go's `netip`: classify, order, test containment. | | A strict integer parse | `stdx.fmt.atoi` | One grammar, no bases, no underscores. `std.fmt.parseInt` accepts more. | | A binary wire format | `stdx.wire.Writer` | Forward-only over caller-owned bytes, byte order fixed at comptime, backpatch slots. | | Hex bytes in source | `stdx.fmt.comptimeHex` | A bad literal is a compile error, not a runtime one. | | A Crockford base32 token | `stdx.base32` | The decode is the validation. | | A UUID | `stdx.Uuid` | v4 and v7, parse and format. | | A clock read without an `Io` value | `stdx.time` | Include a cached clock and a log rate limiter. | | A set of deadlines over `Io.Timestamp` | `stdx.timers` | Arm, stop, and repeat by handle, without period drift. | | Log lines moving off worker threads | `stdx.slot_ring.Mpsc` | Bounded. Producers never block. Linux only. | | Allocations from a fixed-size pool | `stdx.heap.SizeClassPool` | Also `SlabAllocator`, for whole-page release. | | A `memcpy`, `memset`, or `memmove` in a profile | `fastmem` | The same calls, measured against the target. `std` and the allocators get them. | Where the whole job is the thing, baskingspot publishes a package. Same org as `stdx`, and each is a separate `zig fetch`: | The job | Package | Why | | ------------------------------------- | ---------- | ----------------------------------------------------------- | | gzip, zlib, Snappy, or Brotli | `compress` | std has flate, the LZMA family, and a zstd decoder only. | | A TLS 1.3 handshake | `tls` | Sans-I/O, caller-owned buffers. | | A test runner or a Go-style benchmark | `testingx` | Replaces the built-in runner; `benchstat` reads the output. | | A `getopt_long` flag loop | `cli` | Short clusters, long options, and the `--` separator. | ## When your own type is the answer A fixed capacity turns a large input into `error.NoSpaceLeft`. If the size comes from input you do not control, reach for the growing type. When a primitive loses, write one comment saying what you checked: ```zig // stdx.buffer.Array caps at comptime; this frame length comes off the wire. ``` That comment is what review asks for, and it is the only record of a decision the next reader would otherwise re-open. ## Write it in this shape The Zig an agent writes by default is not wrong, it is just not this. Read [style.md](references/style.md) before writing more than a function. The rules that change the most: - `const x: T = .{ ... }`, type on the left, anonymous literal on the right. Never the type twice. - `return switch (...)` and `return if (...)`. One return, flow as an expression. - Success and failure are an error union, never a tagged union. A syntax error is `error.SyntaxError`; its position goes in a caller-owned `Diagnostics` struct passed by pointer through the options, the way `std.json.Scanner.enableDiagnostics` does it. An arm with `.document` and `.failure`, or `.doc` and `.diagnostic`, is a Rust `Result` wearing Zig clothes, and review sends it back. - A stateful type is its own file, named for it, holding `const Server = @This();`. - Alias at the top of the file. A body never says `std.mem.eql`. - No `usize` in a field or a local. Explicit widths, cast at the boundary. - A bool that gates more than one decision is an enum or a `std.EnumSet`. - A bit tag is a `packed struct(u64)`, not shifts and masks. - 70 lines per function. Comments say why. - Method order is `init`, `deinit`, public API, helpers. The allocator is the first argument. - A command-line tool writes through `stdx.stdio`, whose streams never return an error, instead of plumbing `try` through every print. ## Write tests with testingx Add `testingx` and point `.test_runner` at it in every project that has tests. This is not a style preference. The built-in runner prints nothing on success and a block of interleaved output on failure, which is hard to read from a pipe and impossible to diff across runs. `testingx` prints one stable line: ```text testingx: 13 passed, 0 failed, 0 skipped (of 13 total) in 41ms (seed: 0x8f2a) ``` You can read that, and so can a script. Wire it once: ```sh zig fetch --save https://baskingspot.dev/testingx/vX.Y.Z.tar.gz ``` ```zig const testingx = b.dependency("testingx", .{ .target = target }); const tests = b.addTest(.{ .root_module = mod, .test_runner = .{ .path = testingx.path("src/runner.zig"), .mode = .simple }, }); const run_tests = b.addRunArtifact(tests); run_tests.addArg(b.fmt("--seed=0x{x}", .{b.graph.random_seed})); ``` `.mode = .simple` skips the binary protocol the built-in runner uses, which is also why a test that writes to stdout cannot deadlock. Never import `src/runner.zig` from your own code; a test runner compiles as its own module. What else it gives you: - **Benchmarks.** A benchmark is `pub fn benchmarkDecode(b: *testingx.B) !void` beside the tests, registered in a suite file. It prints the Go benchmark format, so `benchstat` compares runs. `std.testing` has no benchmark support at all, so a benchmark is the reason to reach for this package even if the runner were equal. - **Leaks and error logs fail.** A test that leaks memory fails, and a test that logs at error level fails, with no opt-in. - **Fixtures are files.** `@embedFile` bytes decode at comptime, and a txtar archive becomes sections by name, so a test table stays out of the source. The [guide](https://baskingspot.dev/testingx/index.md) covers the flags, sub-benchmarks, and fixtures. ## Reviewing Zig For every new type and every parse loop in the diff, answer two questions: what primitive is this, and why is it not the standard one? The tells of a type that should not exist: - a struct holding `[]T` and a length, or a capacity and an allocator - a `while` that scans and parses the same bytes - a `switch` over string literals returning a value - a `deinit` on a type whose storage could have lived in the value - arithmetic on bit offsets, or a `@popCount` of a hand-kept validity mask Every new type in the diff is a primitive from the tables above, or it carries the comment. ## Before you call it done - Run `ziglint` over the tree and fix every finding. It catches what reading your own code does not: an empty `catch {}` that swallows errors (Z026), an inline `@import` that should be a top-level const (Z028), a line over the limit (Z024), a `deinit` that leaves `self` pointing at freed memory (Z030). Most baskingspot dev shells provide it. When it is not on PATH, say so in the final message instead of skipping it in silence. For a code you do not recognise, the rule's page is `https://github.com/rockorager/ziglint/blob/main/docs/rules/Z024.md`. - `zig build test` passes and its output is one line you can read. ```` ## File: eval/scaffold/.agents/skills/zig-016/references/linux-raw-layer.md size: 4535 sha: fee552a4da6fc4dc3cd1e40bfee3c5e11d35024d upstream: https://github.com/baskingspot/skills/blob/main/eval/scaffold/.agents/skills/zig-016/references/linux-raw-layer.md ````text # The Linux raw layer in Zig 0.16 Checked against the std tree that `zig env` prints for 0.16.0 on aarch64-linux. The numbers and the disappeared functions move with the release, so grep before relying on any of this. ## The layers | Layer | What it is | Reach for it when | | ---------------------- | ----------------------------------------------- | --------------------------------------- | | `std.Io` | the interface; functions take an `Io` | always first | | `std.posix` | 54 functions left; the medium layer is gone | `setsockopt`, `mmap`, signals, `openat` | | `std.posix.system` | `std.os.linux` without libc, `std.c` with | one call the layer above does not wrap | | `std.os.linux` | one wrapper per syscall, each returning `usize` | a syscall that has no portable wrapper | | `std.os.linux.IoUring` | the raw ring wrapper | io_uring | `syscall0` through `syscall6` live in `std/os/linux/.zig` and take a `SYS` value. `SYS` is an arch-switched enum, in `std/os/linux/syscalls.zig`. ## `linux.E` is an enum, not an error set `linux.E` is a plain enum of errno values. It is not an error set, so `linux.E!T` is not a type and an errno value is not an error. Declare the error set the code actually needs and map onto it: ```zig const SysError = error{ WouldBlock, ConnectionReset, BrokenPipe, Interrupted, Unexpected }; fn toError(e: linux.E) SysError { return switch (e) { .AGAIN => error.WouldBlock, .CONNRESET => error.ConnectionReset, .PIPE => error.BrokenPipe, .INTR => error.Interrupted, else => error.Unexpected, }; } fn check(raw: usize) SysError!u32 { const errno = linux.errno(raw); return if (errno == .SUCCESS) @intCast(raw) else toError(errno); } ``` ## What `std.posix` still has 54 functions. The ones worth naming: `read`, `setsockopt`, `getpeername`, `mmap`, `munmap`, `mremap`, `msync`, `kill`, `raise`, `openat`, `getppid`, `sched_getaffinity`, the signal-set helpers, `sigaltstack`, `sysctl`, `dl_iterate_phdr`, `reboot`. Gone: `socket`, `bind`, `listen`, `accept`, `epoll_*`, `pipe2`, `sendmsg`, `recvmsg`, `splice`, and `fcntl` as a `posix` function. Each lives in `std.os.linux` under its own name. ## `std.os.linux` wrappers `socket`, `setsockopt`, `bind`, `listen`, `accept4`, `connect`, `shutdown`, `sendmsg`, `recvmsg`, `sendto`, `recvfrom`, `epoll_create1`, `epoll_ctl`, `epoll_wait`, `pipe2`, `fcntl`, `ioctl`, `getsockname`, `getpeername`, and the `io_uring_*` calls. Each returns a raw `usize`, decoded with the pattern above. There is no bare `send` or `recv`. Use `sendto`/`recvfrom`, or the `msg` forms. `iovec` comes from `std.posix`; `linux.iovec_const` is private. ## Two landmines `std.posix.setsockopt` maps `.INVAL => unreachable`, which is UB in ReleaseFast and a process kill in Debug. Use it for options where `EINVAL` is a programming bug, such as `TCP_NODELAY` or `SO_REUSEADDR`. For any option whose `EINVAL` is a legitimate runtime failure, call `linux.setsockopt` and decode errno. It also type-checks `SO_RCVTIMEO` and `SO_SNDTIMEO`, so a `timeval` takes microseconds, not nanoseconds, and an oversized value returns `error.TimeoutTooBig`. There is no `linux.splice` function, only `SYS.splice`. Six arguments through `syscall6`: ```zig fn splice(fd_in: i32, off_in: ?*const u64, fd_out: i32, off_out: ?*const u64, len: usize, flags: u32) SysError!usize { const raw = linux.syscall6(.splice, @as(u64, @bitCast(@as(i64, fd_in))), @intFromPtr(off_in), @as(u64, @bitCast(@as(i64, fd_out))), @intFromPtr(off_out), len, flags); return check(raw); } ``` ## `IoUring` vs `Io.Uring` `std.os.linux.IoUring` is the wrapper to use. `std.Io.Uring` is the unfinished `Io.Evented` implementation, and its functions take `*Evented`. They are different files. `IoUring` gives you `init`, `get_sqe`, `submit`, `cq_ready`, `copy_cqes`, and builder methods that return `*io_uring_sqe` (`read`, `write`, `splice`, `accept_multishot`, `timeout`, and more). `user_data` is left to the caller. Grep `pub fn` in `std/os/linux/IoUring.zig` before assuming a builder exists. ## What is not here `Io.Evented` has no networking yet. `Io.Threaded` maps the surface onto blocking syscalls, so it is the one to use when portability matters more than the last microsecond. ```` ## File: eval/scaffold/.agents/skills/zig-016/references/style.md size: 7256 sha: 1b354f77a46bf5342599cb601abc74488e1ec005 upstream: https://github.com/baskingspot/skills/blob/main/eval/scaffold/.agents/skills/zig-016/references/style.md ````text # The shape of the Zig The default Zig an agent writes is not wrong. It is just not this. These are the rules that change what the code looks like, not what it does, and they are the ones an agent will not arrive at on its own. A project may adopt a stricter doctrine, such as TigerBeetle's Tiger Style. That doctrine is opt-in, it is applied on purpose, and where it disagrees with this file it wins. ## Expression shape - Type on the left, anonymous literal on the right: `var x: Foo = .init(a, b);`, `const opts: Options = .{ .field = value };`. Never name the type twice. The exception is a `return`, where the signature already carries it: `return .{ .field = value };`. - Control flow as an expression: `return switch (...)`, `return if (...)`. One return, not a return in every branch. Collapse `if (cond) return a; return b;`. - `try` at the call, a centralized `catch` where the error is handled. Drop `try` where nothing can fail. - `@branchHint(.cold)` on the rare error return. - Alias a subexpression used twice in one function. - 70 lines per function. Keep control flow in the parent and push pure computation into helpers. ## File structure 1. `//!` module doc. Never `///` at the top of a file. 2. Imports, with short aliases. 3. `const X = @This();` named for the type. 4. A scoped logger, when the project has one. Hoist `const testing = std.testing;` and keep tests at the bottom of the file they cover. Method order is `init`, `deinit`, public API, private helpers. The allocator is the first argument. A `const` becomes `pub const` only when it leaves the module. Free functions that take an enum become methods on it with a `comptime self`. Comments explain why. A threshold, a protocol detail, or a non-obvious ordering gets a sentence. Document the reason, never the syntax. A magic number with meaning becomes a named constant or an enum tag. Loop counters and bytes quoted from a spec can stay bare. A `[N]u8` or a slice with domain meaning gets a named type alias. ## The file is the type A stateful type is its own file, named for the type. `Server.zig` holds `const Server = @This();`, and a consumer imports the file and uses it as the type. There is no inner `pub const Server = struct { ... }` wrapper. ```zig // src/Server.zig const Server = @This(); pub const Config = struct { ... }; const Phase = enum { ... }; config: Config, ring: Ring, pub fn init(gpa: Allocator, config: Config) !Server { return .{ ... }; } pub fn deinit(self: *Server) void { ... } fn dispatch(self: *Server, cqe: linux.io_uring_cqe) !void { ... } // consumer const Server = @import("Server.zig"); var server: Server = try .init(gpa, .{}); ``` Every file-scope declaration is a member, the tests at the bottom exercise the real type, and a helper type nests inside the one that owns it. A file of standalone functions stays lowercase, `sys.zig` or `mem.zig`, and earns its existence only with real content. One function is not a file. ## Imports: alias densely, never qualify in a body The import block is the table of contents, so bodies stay short. ```zig const std = @import("std"); const assert = std.debug.assert; const mem = std.mem; const testing = std.testing; const Io = std.Io; const Allocator = std.mem.Allocator; const print = std.debug.print; const linux = std.os.linux; const Ring = linux.IoUring; ``` Every std path a body uses gets an alias, including single-use ones. A body never says `std.mem.eql` or `std.debug.assert`. A deep type path lifts to a PascalCase alias. The exception is kernel types in snake_case, `linux.io_uring_cqe` and `linux.cmsghdr`. They stay qualified, because a PascalCase alias claims it is a Zig type, and [ziglint](https://github.com/rockorager/ziglint) flags the mismatch. ## A bool is a smell `true` and `false` at a call site carry no meaning. A two-variant enum names the state: `CloseMode = enum { graceful, abortive }`, and `conn.close(.graceful)` reads. `std.EnumSet(Flag)` holds the flags that can be set at once. A `phase` enum replaces a pile of booleans and grows into a state machine. A bool is fine where it is the data: a packed-struct bit, an `atomic.Value(bool)`, presence that is really `?T != null`, generated code. The test for a latch: does the bit change behaviour in more than one place? If yes it is a flag, and it belongs in an `EnumSet`. If it only says something exists, it is presence. When in doubt, name the state. ## No `usize` in state Use an explicit width for a struct field or local state: `u64`, `u32`, `u16`. Sizes stay deterministic instead of tracking the pointer width. `usize` appears only where a std API demands it, cast at the boundary. A bit tag is a `packed struct(uN)`, not shift arithmetic. `op: 8, slot: 16, gen: 16, spare: 24` becomes a `packed struct(u64)` with those fields, and `@bitCast` converts both directions. The type system does the packing, so there is no `packTag` and no `unpackTag`. The first declared field sits at bit 0, so declare least-significant first to keep a most-significant-first wire layout. Explicit bit alignment on a field is rejected by the compiler. Nested packed structs and bools are legal fields; plain structs such as `EnumSet` are not. ## Buffers A hand-rolled `buf: [N]T` plus `len` is the container the language already ships. Use `stdx.buffer.Array(T, capacity)` for storage inside the value, and `stdx.buffer.Slice(T)` for a read cursor over memory you own. Append when capacity is known good with `appendAssumeCapacity`, not `append` plus `catch unreachable`. Call `deinit` in teardown. A list that grows with no known bound is `std.ArrayList(T)`. Never `gpa.alloc` for a list the type owns. ## Arithmetic and safety ReleaseFast wraps `+` and `-` silently, truncates `@intCast`, and erases `std.debug.assert`. Pick the tool by where the operands come from: - A length, count, or offset from input or the wire is validated in every build mode, and returns an error when the failure is recoverable. Check before mutating, and order the check so it cannot wrap itself. - A value the kernel or an ABI reports is checked in every mode. - A programmer invariant, such as a capacity contract or a refcount, is a `std.debug.assert`, paired with an `assumeCapacity`-style sibling. - Wraparound that is the semantics, such as a generation or an epoch, is written with `+%` and `-%` on purpose. `@panic` is for corruption already in hand, never for input you caught. A bounds check that fires before damage is recoverable: return the error, unwind the scope, log loudly. Aborting on something you detected is pure cost, and an abort reachable from the network is a denial of service. ## Zeroing `std.crypto.secureZero` for a buffer that can hold secret material. `@memset` only for hygiene on a buffer that never holds a secret, with a comment saying so. The difference is dead-store elimination: the optimizer may drop a `@memset` to a buffer it can see is dead, and it cannot drop `secureZero`. Classify by what the buffer can hold, not what it holds where the zeroing happens. ## Logging Scope the logger per module with `std.log.scoped(.fetch)` rather than reaching for one global. Pick the level by the consequence, not by how interesting the line is. ```` ## File: eval/scaffold/.agents/skills/zig-016/references/zig-0.16-changes.md size: 14953 sha: 81910e2b2612aad98d7c667f71e08856b38ee299 upstream: https://github.com/baskingspot/skills/blob/main/eval/scaffold/.agents/skills/zig-016/references/zig-0.16-changes.md ````text # Zig 0.16 changes — verified detail All examples verified against zig 0.16.0 and the 0.16.0 release notes. Source of truth: `zig env` → `.std_dir`. ## Table of contents 1. [I/O as an Interface](#io-as-an-interface) 2. [Juicy Main](#juicy-main) 3. [File system migration table](#file-system-migration-table) 4. [Tasks, cancelation, and Io implementations](#tasks-cancelation-and-io-implementations) 5. [Language changes](#language-changes) 6. [Format and error-set changes](#format-and-error-set-changes) 7. [Migrating off @cImport](#migrating-off-cimport) ## I/O as an Interface Anything that can block control flow or introduce nondeterminism takes an `Io` instance. `Io` is passed by value; implementations fill a vtable. Custom `Io` implementations are legal. The interface lives in `std/Io.zig` (vtable entries like `netListenUnix`, `netConnectUnix` are visible there). Key types: - `std.Io.Writer` — only writer type. Buffering is in the interface, `flush()` is explicit. - `std.Io.Reader` — only reader type. - `std.Io.Writer.Allocating` — writes to allocated memory; has an `alignment: std.mem.Alignment` field now; `toOwnedSlice`. - `std.Io.File.Writer = .init(file, io, &buffer)` / `file.writer(io, &buffer)`. - `std.Io.File.Reader` via `file.reader(io, &buffer)`; `&.{}` for unbuffered. - `std.Io.Writer = .fixed(buffer)` / `std.Io.Reader = .fixed(data)` — replaces FixedBufferStream. - `Io.Writer.Allocating` for building strings: `.init(allocator)`, `.writer.print(...)`, `.toOwnedSlice()`. Custom formatters: `pub fn format(self: @This(), w: *std.Io.Writer) std.Io.Writer.Error!void`, invoked with `{f}`. ## Juicy Main `std.process.Init` fields: `minimal` (argv + environ), `arena` (`*ArenaAllocator`, process lifetime, threadsafe), `gpa` (Allocator, threadsafe), `io` (Io), `environ_map` (`*Environ.Map`), `preopens`. `Init.Minimal` fields: `environ: Environ`, `args: Args`. Arg iteration without allocation: ```zig pub fn main(init: std.process.Init.Minimal) void { var args = init.args.iterate(); while (args.next()) |arg| { ... } } ``` Env access: `init.environ.getPosix("HOME")`, `init.environ_map` for the full map. Env vars are no longer global state — pass what you need down as parameters. ## File system migration table | 0.15 | 0.16 | | -------------------------- | ----------------------------------------------------------------------------------------------------------- | | `std.fs.File` | `std.Io.File` | | `std.fs.Dir` | `std.Io.Dir` | | `std.fs.cwd()` | `std.Io.Dir.cwd()` | | `fs.File.read`/`readv` | `Io.File.readStreaming` | | `fs.File.pread`/`preadv` | `Io.File.readPositional` | | `fs.File.write`/`writev` | `Io.File.writeStreaming` | | `fs.File.pwrite` | `Io.File.writePositional` | | `fs.File.writeAll` | `Io.File.writeStreamingAll` | | `fs.File.setEndPos` | `Io.File.setLength` | | `fs.File.getEndPos` | `Io.File.length` | | `fs.File.seekTo`/`seekBy` | `Io.File.Reader.seekTo` / `.seekBy`, `Io.Writer.seekTo` | | `fs.File.getPos` | `Io.File.Reader.logicalPos`, `Io.Writer.logicalPos` | | `fs.Dir.makeDir` | `Io.Dir.createDir` | | `fs.Dir.makePath` | `Io.Dir.createDirPath` | | `fs.Dir.makeOpenDir` | `Io.Dir.createDirPathOpen` | | `fs.Dir.chmod`/`chown` | `Io.Dir.setPermissions`/`setOwner` | | `fs.Dir.realpath` | `Io.Dir.realPathFile` | | `fs.Dir.readFileAlloc` | `Io.Dir.cwd().readFileAlloc(io, path, allocator, .limited(n))` — limit reached is now `error.StreamTooLong` | | `fs.File.readToEndAlloc` | `file.reader(io, &.{}).interface.allocRemaining(allocator, .limited(n))` | | `fs.path` | `std.Io.Dir.path` (deprecated alias) | | `fs.copyFileAbsolute` etc. | `std.Io.Dir.copyFileAbsolute` etc. | | `fs.openSelfExe` | `std.process.openExecutable` | | `fs.selfExePathAlloc` | `std.process.executablePathAlloc` | | `fs.Dir.setAsCwd` | `std.process.setCurrentDir` | `file.close()` is now `file.close(io)`. `File.Stat` access time is optional. `File.Mode` → `Io.File.Permissions`. Memory-map sync points are explicit (`File.MemoryMap`). Removed with no replacement: most `*AbsoluteZ`/`*W` variants, `fs.getAppDataDir`. ## Tasks, cancelation, and Io implementations Spelling is "cancelation" (single l) throughout std. - `io.async(fn, args)` → `Future(T)`, infallible, may just call the function inline. `io.concurrent(...)` — must run concurrently, can fail `error.ConcurrencyUnavailable`. - `Future.await(io)` / `Future.cancel(io)`. `cancel` = await + interrupt request → `error.Canceled`. Even `Io.Threaded` supports it (signal → EINTR → check). - `error.Canceled` is baked into cancelable I/O error sets. Only the cancel requester may ignore it. Alternatives: propagate, `io.recancel()`, or `io.swapCancelProtection()`. - `Io.Group` — O(1) spawn of N tasks; `group.async(io, fn, args)`, `group.await(io)`, `group.cancel(io)`; always `defer group.cancel(io)`. - `Io.Batch` — operation-level concurrency (`FileReadStreaming`, `FileWriteStreaming`, `DeviceIoControl`, `NetReceive` currently). `io.operateTimeout` adds timeouts to batchable ops. - `io.checkCancel()` — extra cancelation points in long CPU-bound loops. - `std.Random.IoSource = .{ .io = io }` → `.interface()` for a Random. - `Io.Queue(T)`, `Io.Select`, `Io.Clock`/`Duration`/`Timestamp`/`Timeout` exist for units-typed time work. Implementation status: | Impl | Status | | ------------- | -------------------------------------------------------------------------- | | `Io.Threaded` | complete, well-tested, default; `-fsingle-threaded` loses task concurrency | | `Io.Evented` | WIP (M:N green threads); **no networking yet** | | `Io.Uring` | PoC (Evented on io_uring); unfinished | | `Io.Kqueue` | PoC | | `Io.Dispatch` | PoC (GCD) | | `Io.failing` | supports no operations (useful in tests) | For a custom event loop, build on `std.os.linux` + `std.os.linux.IoUring` directly. See [linux-raw-layer.md](linux-raw-layer.md). Sync primitives that do not need `Io`: lock-free ones only. Everything contended moved: `Thread.ResetEvent`→`Io.Event`, `WaitGroup`→`Io.Group`, `Futex`→`Io.Futex`, `Mutex`→`Io.Mutex`, `Condition`→`Io.Condition`, `Semaphore`→`Io.Semaphore`. `std.once` removed. `Thread.Pool` removed. `ArenaAllocator` is threadsafe and lock-free now; `ThreadSafeAllocator` removed. ## Language changes - `@Type` is **removed**. Replacement builtins: `@EnumLiteral()`, `@Int(signedness, bits)`, `@Tuple(types)`, `@Pointer(size, attrs, child, sentinel)`, `@Fn(param_types, param_attrs, return_type, attrs)`, `@Struct(layout, backing, names, types, attrs)`, `@Union(layout, backing, names, types, attrs)`, `@Enum(tag_int, mode, names, values)`. Use `&@splat(.{})` for default attrs. `std.meta.Int`/`std.meta.Tuple` deprecated. No `@Float` (use `std.meta.Float`), no `@Array`, no `@Opaque` (write `opaque {}`), no `@Optional`/`@ErrorUnion`/`@ErrorSet` — error sets can no longer be reified. - Small integer → float coercion when every value fits without rounding (`u24`→`f32` yes, `u25`→`f32` no). - `@floor/@ceil/@round/@trunc` can convert float→int directly (result type inferred); `@intFromFloat` deprecated. - Unary float builtins (`@sqrt`, `@sin`, ..., `@round`) forward their result type, so `const x: f64 = @sqrt(@floatFromInt(n));` works now. - Returning the address of a runtime-known local is a compile error: `error: returning address of expired local variable`. - `packed struct`/`packed union` fields may not be pointers. Packed unions require same-`@bitSizeOf` fields or an explicit backing int (`packed union(u16)`); explicit backing ints allowed and required in extern contexts (also for enums: `enum(u8)`). - Packed types and enums work as switch prong items (compared by backing integer). - Runtime vector indexing forbidden; coerce to array: `const arr: [n]T = vector;`. - Vectors/arrays no longer coerce in-memory through error unions. - Zero-bit tuple fields are no longer implicitly comptime. - `@cImport` deprecated — move C imports to `b.addTranslateC` + a `.h` file. Full recipe: [Migrating off @cImport](#migrating-off-cimport). Build system additions: local package overrides, project-local dependency fetching, test timeouts (`b.addTest` timeout options), `--error-style`, `--multiline-errors`. ## Format and error-set changes - `{D}` duration specifier removed: `writer.print("{f}", .{std.Io.Duration{ .nanoseconds = ns }})`. - `std.fmt.Formatter` → `Alt`; `std.fmt.format` → `Io.Writer.print`; `FormatOptions` → `Options`; `bufPrintZ` → `bufPrintSentinel`. - leb128: `std.leb.readUleb128` → `std.Io.Reader.takeLeb128`. - Error renames: `RenameAcrossMountPoints`/`NotSameFileSystem` → `CrossDevice`; `SharingViolation` → `FileBusy`; `EnvironmentVariableNotFound` → `EnvironmentVariableMissing`; `Io.Dir.rename` returns `DirNotEmpty` instead of `PathAlreadyExists`. - `std.meta.intToEnum` deprecated → `std.enums.fromInt` (returns `?Enum`, use `orelse`, not `catch`). - `std.compress.flate`: DEFLATE compression now exists in std (0.15's was broken); `Decompress` on `Io.Reader`/`Writer`. - `SegmentedList`, `meta.declList`, `Io.GenericWriter`, `Io.AnyWriter`, `Io.null_writer`, `Io.CountingReader`, `Thread.Mutex.Recursive` removed. - Child processes: `std.process.spawn(io, .{ .argv, .stdin, .stdout, .stderr })`, `std.process.run(allocator, io, .{...})`, `std.process.replace(io, .{ .argv })`. - `std.mem` cut family: `cut`, `cutPrefix`, `cutSuffix`, `cutScalar`, `cutLast`, `cutLastScalar` — splitting without allocation. ## Migrating off `@cImport` Deprecated; C translation moves to the build system. `@cImport` still compiles in 0.16.0 with no warning, so `grep -rn "@cImport"` is the only reliable way to find stale sites. The `@cInclude` list becomes a plain header file, `b.addTranslateC` wraps it, and consumers import an ordinary module. Before — one Zig file held the block, importers pulled the const: ```zig // c.zig pub const c = @cImport({ @cInclude("stdio.h"); @cInclude("GLFW/glfw3.h"); }); // callers: const c = @import("c.zig").c; ``` After — `src/c.h` holds the includes: ```c #include #include ``` `build.zig` owns translation: ```zig const translate_c = b.addTranslateC(.{ .root_source_file = b.path("src/c.h"), .target = target, .optimize = optimize, }); translate_c.linkSystemLibrary("glfw", .{}); const exe = b.addExecutable(.{ .name = "demo", .root_module = b.createModule(.{ .root_source_file = b.path("src/main.zig"), .target = target, .optimize = optimize, .imports = &.{ .{ .name = "c", .module = translate_c.createModule() }, }, }), }); ``` Callers import by module name: `const c = @import("c");`. The translated declarations are identical to what `@cImport` produced. `TranslateC` method → compiler flag (verified in `std/Build/Step/TranslateC.zig`): | Method | Flag | | ------------------------------ | ------------------------------------ | | `addIncludePath` | `-I` | | `addSystemIncludePath` | `-isystem` | | `addAfterIncludePath` | `-idirafter` | | `addFrameworkPath` | `-F` (macOS frameworks) | | `addSystemFrameworkPath` | `-iframework` | | `addConfigHeader` | `-I` the generated header dir | | `defineCMacro(name, value)` | `-D name=value` (value `null` → `1`) | | `linkSystemLibrary(name, .{})` | resolves and links the system lib | Details that matter during migration: - `.link_libc` defaults to `true` in `addTranslateC` options; pass `false` only for headers that need no libc. In 0.15 the same condition surfaced as a compile error — `error: C import failed`, `note: libc headers not available; compilation does not link against libc` (verified on 0.15.2) — unless the compile step called `linkLibC()`. Freestanding-only headers (`stdint.h` and friends) never needed it. - `createModule()` is private to this package. Use `addModule("c")` to expose the bindings to dependent packages. - `getOutput()` is the translated source as a `LazyPath`. Feed it to `translate_c.addCheckFile(&.{"expected symbol"})` and wire the returned step's `.step` into a test step to assert the translation in CI. - For customization beyond the defaults (decl renaming, header exclusion), depend on the official package: . ```` ## File: eval/scaffold/.agents/skills/zig-016/references/zig-0.16.md size: 12088 sha: b58f9b6c57fc462c19029132e229f730b56b1669 upstream: https://github.com/baskingspot/skills/blob/main/eval/scaffold/.agents/skills/zig-016/references/zig-0.16.md ````text # Zig 0.16 LLM training data covers Zig 0.11-0.15 at best. Zig 0.16 has massive breaking changes. Rule zero: verify APIs against the pinned toolchain, not memory. ```bash zig env # .std_dir = the std source for THIS zig ``` `zig env` prints `.std_dir`. Grep that tree when a signature matters. It is the source of truth, it is in the toolchain, and it is cheap. `zigdoc` is a nicer way to read the same source when you have it ([rockorager/zigdoc](https://github.com/rockorager/zigdoc)). ## "Removed" usually means "moved" — grep before you hand-roll 0.16 relocated huge API surfaces without renaming the capability. When the release notes say a type or function was removed, ask where it went before writing your own: - `std.posix.ucontext_t` removed → signal-frame parsing lives in `std.debug.cpu_context.fromPosixSignalContext` (gives `getPc`/`getFp` per arch). - `std.net` DNS "gone" → `std.Io.net.HostName.lookup` / `HostName.connect` is the resolver; `Io.Threaded` implements it. `IpAddress.parse` being literal-only is about parsing, not resolution. - `std.time.Timer`/`Instant`/`*Timestamp` removed → `std.Io.Timestamp` (below). All three were relearned the hard way by hand-rolling something std already had. A vtable grep (`grep -n 'netLookup\|pub fn' std/Io.zig`) takes ten seconds. ## Juicy Main — `main` takes `std.process.Init` ```zig pub fn main(init: std.process.Init) !void { const gpa = init.gpa; // general purpose allocator, threadsafe const io = init.io; // default Io implementation const arena = init.arena.allocator(); // process-lifetime, threadsafe const args = try init.minimal.args.toSlice(init.arena.allocator()); // init.environ_map: *Environ.Map — env vars are NOT global anymore } ``` - argv and environ exist **only** through this parameter. Global argv/env access is gone. - `std.process.Init.Minimal` is the smaller variant (argv + environ only, no gpa/io). - Use `std.testing.io` in tests, like `std.testing.allocator`. `std.testing.environ` for env. ## I/O as an interface — everything takes `Io` `std.fs.File` → `std.Io.File`. `std.fs.Dir` → `std.Io.Dir`. `std.fs.cwd()` → `std.Io.Dir.cwd()`. `file.close()` → `file.close(io)`. ```zig // stdout, buffered: var buf: [4096]u8 = undefined; var writer: std.Io.File.Writer = .init(.stdout(), io, &buf); defer writer.interface.flush() catch {}; try writer.interface.print("hello {s}\n", .{"world"}); // one-shot: try std.Io.File.stdout().writeStreamingAll(io, "Hello, world!\n"); // reading: var file_reader = file.reader(io, &.{}); // &.{} = empty buffer, unbuffered const contents = try file_reader.interface.allocRemaining(allocator, .limited(max)); // FixedBufferStream is gone: var writer: std.Io.Writer = .fixed(buffer); var reader: std.Io.Reader = .fixed(data); ``` - No `Io` at hand: `var threaded: std.Io.Threaded = .init_single_threaded; const io = threaded.io();` — a workaround, not a pattern; thread `Io` through instead. - `Io.Threaded` is complete (the default `init.io`). `Io.Evented`/`Io.Uring`/`Io.Kqueue` are WIP. - Style: alias `const Io = std.Io;` per file, and use the method form (`io.random(&buf)`, `io.sleep(...)`, `futex.futexWake(io)`), never `Io.random(io, ...)`. ## Clock and randomness in 0.16 `std.time` is unit constants plus `std.time.epoch` — **no clock functions at all**. A `std.time.microTimestamp()` call compiles only when lazy analysis never reaches it (see the landmine section). - Time reads: `std.Io.Timestamp.now(io, .awake)` (monotonic) or `.now(io, .real)` (wall). `Io.Timestamp` is a plain value type: `.{ .nanoseconds = n }` constructs one with no io, and `durationTo`/`addDuration`/`toSeconds`/`toMilliseconds` are pure value math. Many projects wrap a `timex` module around the raw clock syscall instead of threading io just for time — that is a legitimate pattern. - Randomness: `io.random(&buf)` for bytes (`io.randomSecure` for secrets). For a `std.Random` interface, seed a `std.Random.DefaultPrng` once per thread from `io.random` and keep it — preferred over `std.Random.IoSource`, whose returned `Random` borrows the IoSource struct: return it from a helper and the borrow dangles. `std.Random.DefaultCsprng` (ChaCha) when the stream should stay unpredictable. - Tests: `var prng: Random.DefaultPrng = .init(testing.random_seed);` inline at the test site, then `prng.random()`. No helper that vends a `Random` — it needs a fn-local static to keep the borrow alive, which is machinery for a two-line problem. ## The lazy-analysis landmine Zig analyzes lazily. A `switch` on a comptime-known build option never analyzes dead arms, so a call to a removed API can sit in a pruned arm and survive every green build — until someone builds the other flag combination. Same for code paths only reachable under a different `-D` option. Defense: build the option matrix, not just the default. Run BOTH `zig build test` AND `zig build` (a green test build with a broken `run()` is a real observed failure mode), and any non-default build flags the project ships. ## `std.posix` was gutted The medium layer is gone. Survivors include `read`, `setsockopt`, `mmap`/`munmap`, `kill`/`raise`, `openat`, `sched_getaffinity`, signal-set helpers, `sigaltstack`. There is no `std.posix.write` — write through `Io`, or `linux.write` at the raw layer. Everything else: go **higher** (`std.Io`) or **lower** (`std.posix.system` — `std.os.linux` without libc, `std.c` with libc). **Connecting and listening need `.mode`.** `std.Io.net.ConnectOptions` and `ListenOptions` declare `mode: Socket.Mode` with no default, so `.{ .mode = .stream }` is mandatory and `addr.connect(io, .{})` does not compile. `protocol` and `timeout` do have defaults. **setsockopt landmine:** `std.posix.setsockopt` maps `EINVAL` to `unreachable` — UB in ReleaseFast. For any option where EINVAL is a legitimate runtime failure, use the raw layer and decode errno yourself. It also type-checks `SO_RCVTIMEO`/`SO_SNDTIMEO`: the `timeval` is validated and a too-large value returns `error.TimeoutTooBig`, so pass microseconds (`std.time.us_per_ms`), not nanoseconds. See [linux-raw-layer.md](linux-raw-layer.md). ## `std.Io` error sets are narrow An `Io` call fails with its own small error set, and `try` or `catch |e| return e` will not widen it into a function whose error union is broader. Declare the error set you actually return and map into it: ```zig fn readAll(reader: *Io.Reader) Error!void { reader.readAlloc(gpa, n) catch |e| switch (e) { error.OutOfMemory => return error.OutOfMemory, error.ReadFailed => return error.ReadFailed, error.StreamTooLong => return error.Truncated, }; } ``` The compiler's message names the two sets: `expected type 'error{ReadFailed, StreamTooLong}', found 'error{EndOfStream}'`. Read it as "these are the errors you did not account for". ## `std.mem` renames — "index of" is now "find" `indexOf` → `find`, `indexOfScalar` → `findScalar`, `indexOfAny` → `findAny`, `lastIndexOf` → `findLast`, `indexOfPos` → `findPosLinear` family. The old names survive as `pub const indexOf = find`, marked deprecated, so `std.mem.indexOf` still compiles. A green build is not evidence that the call site is current; grep for the old names. ## Other 0.16 breaks, one line each - `@Type` removed → `@Int`, `@Struct`, `@Union`, `@Enum`, `@Pointer`, `@Fn`, `@Tuple`, `@EnumLiteral()`. - `@cImport` deprecated (still compiles, no warning) → `b.addTranslateC` in build.zig + `const c = @import("c")`. Recipe: [Migrating off @cImport](zig-0.16-changes.md#migrating-off-cimport). - Sync primitives moved: `Thread.ResetEvent`→`Io.Event`, `WaitGroup`→`Io.Group`, `Futex`→`Io.Futex`, `Mutex`→`Io.Mutex`, `Condition`→`Io.Condition`, `Semaphore`→`Io.Semaphore`. `std.once` and `Thread.Pool` removed. `ArenaAllocator` is threadsafe/lock-free; `ThreadSafeAllocator` removed. - `std.crypto.random` gone → `io.random(&buf)` / `io.randomSecure(&buf)`. - `{D}` format specifier removed → `{f}` with `std.Io.Duration`. - `std.ArrayList` is unmanaged: init `.empty`, allocator per mutating call. `ArrayListUnmanaged` is a deprecated alias. - Managed containers removed (`AutoArrayHashMap` → `array_hash_map.Auto`, etc.); `PriorityQueue`/`PriorityDequeue` lost their allocator field. - Cast builtins are single-argument, return type inferred: `const x: DestType = @ptrCast(ptr);` - Type reflection tags lowercase: `.int`, `.float`, `.@"struct"`, `.@"enum"`. - Structs/arrays have no `==`; use `std.meta.eql` / `std.mem.eql`. - Returning the address of a local is a compile error ("expired local variable"). - Pointers are forbidden in `packed struct`/`packed union`. `extern` enums/packed types need explicit backing ints. - Runtime vector indexing is forbidden — coerce to array first. - Error renames: `RenameAcrossMountPoints`/`NotSameFileSystem`→`CrossDevice`, `SharingViolation`→`FileBusy`, `EnvironmentVariableNotFound`→`EnvironmentVariableMissing`. - Child processes: `std.process.spawn(io, .{ ... })`, `std.process.run(allocator, io, .{...})`. - `std.meta.intToEnum` → `std.enums.fromInt` (returns `?Enum`, not an error union — `orelse`, not `catch`). - `std.mem.copyForwards`/`copyBackwards` → the `@memmove` builtin. Build system: `b.addExecutable(.{ .name, .root_module = b.createModule(.{ .root_source_file = b.path("src/main.zig"), .target, .optimize }) })`; `addStaticLibrary()` → `addLibrary(.{ .linkage = .static })`; path strings → `b.path(...)` LazyPaths. ## Security footgun: narrow-type arithmetic in bounds checks Zig evaluates `narrow_type + comptime_int` in the narrow type **before** widening for the comparison: ```zig const len = r.assumeRead(u16); // attacker-controlled length if (remaining < len + 5) return error.UnexpectedEof; // BUG: len + 5 overflows u16 ``` panics (Debug/ReleaseSafe) or is UB (ReleaseFast) before the comparison rejects the oversized input. Remote DoS class. No linter catches it. Always widen first: ```zig if (remaining < @as(usize, len) + 5) return error.UnexpectedEof; ``` ## Style - `camelCase` functions, `snake_case` variables/constants, `PascalCase` types. - Prefer `const foo: Type = .{ .field = value };` over `const foo = Type{...};`. - File order: `//!` doc, `const Self = @This();`, imports, `const log = std.log.scoped(...)`. - Allocators explicit; `errdefer` for cleanup on error paths. - Use `@splat` for uniform array/vector init: `const mask: [4]u8 = @splat(0);` - Extract type aliases for repeated semantic types (`const RecordLen = u16;`, not bare `u16` in every signature). - Tests inline with the code they cover. - Comments explain why, not what. ## Before writing Zig code 1. `zig env` and a grep for any std API you are not certain of. 0.16 renamed too much to guess. 2. If a capability seems missing, grep `.std_dir` for where it moved before hand-rolling it. 3. Read existing code in the project first; match established patterns. 4. After writing, run `zig build test`, `zig build`, and every non-default build-flag combination the project documents. ## Running one module's tests standalone (with dependency modules) To run one module's tests outside `zig build`, for a faster loop and direct stderr, pass the dependency modules on the command line. Each `--dep NAME` comes before the `-MNAME=...` that uses it: ```sh zig test src/root.zig \ --dep dep --Mroot=src/root.zig \ --dep dep_options --Mdep=zig-pkg/dep-*/src/root.zig ``` - `error: module 'X' declared but not used` means the root source file never references `@import("X")`. Wire only the dependencies the root imports. - A dependency whose module needs a generated companion module, such as a `build_options` module, needs that companion named here too. Its `build.zig` says which. - A test runner that prints per suite can hide which vector failed inside a table test. A temporary print in the table runner is faster than a binary search. ```` ## File: README.md upstream: https://github.com/baskingspot/skills/blob/main/README.md ````text

baskingspot

Agent skills for Zig. A skill is a folder of instructions that an agent loads when a task matches its description, and nothing until then. These carry the parts of writing Zig that a model does not do on its own. Written cold, Zig drifts toward C: a struct holding a slice and a length, a `while` over `split` that parses as it scans, tests through the built-in runner, a hand-rolled flag loop. `zig-017` names the primitive behind each of those and carries the 0.16 to 0.17 migration. `zig-016` is the same skill for the previous toolchain. `tiger-style` is the stricter overlay, for code where a bug is data loss. ## Install Any agent that reads the [Agent Skills](https://agentskills.io) format, which is most of them: ```sh npx skills add baskingspot/skills ``` It asks which skills and which agents, then writes each one into that agent's own directory. Add `-g` to install for every project. In [pi](https://pi.dev): ```sh pi install git:github.com/baskingspot/skills ``` Both read `skills/` from this repo, so nothing is written twice. ## What is here | Skill | When an agent loads it | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `zig-017` | Writing new Zig 0.17, or porting a 0.16 tree to it. The 0.16 to 0.17 deltas, the primitive behind whatever is about to be hand-written, and the house style | | `zig-016` | The same for a project still on 0.16: the 0.15 to 0.16 deltas, testingx, and the house style | | `tiger-style` | Reviewing Zig for safety, assertions, bounded flow, naming, or structure, or when a project already follows it | Install the one that matches the project's `build.zig.zon`. `zig-017` covers everything `zig-016` does, so a project that ports does not need both. What `zig-017` cannot tell you yet: stdx and testingx declare `minimum_zig_version = "0.16.0"` and fail to configure on 0.17, on `b.graph.random_seed` in their own build scripts. The skill says so, and says what to write instead until they port. `tiger-style` is a choice, not a version match: it is TigerBeetle's doctrine, restated, and it puts safety over performance over developer experience in a way not every project wants. Each skill carries reference files under `references/`. The description and the body are what an agent loads, and a reference is read only when the body points at one. ## How we know it works `eval/` holds the harness. `eval/scaffold/` is a vanilla Zig project with the skills vendored under `.agents/skills/`, `eval/prompt.md` is the task, and `eval/results/` holds what came back. Three rounds so far, six models, with a no-skills control in the first two. The results changed the skills more than once: a line telling the agent to hand over a fetch line instead of adding a dependency left half the runs with no dependency at all, and removing it took stdx from none of six to five of six. The write-up for all three rounds is in `eval/results/`, with each round's skills pinned to a commit or marked as an uncommitted draft. ## Working here `nix develop` provides every tool, and `direnv allow` loads it on entry. `just` lists the recipes. `just ci` runs what CI runs: `skills-ref validate` for the specification, `scripts/check_skills.py` for this repo's rules, and the usual formatters and linters. `just sizes` prints what each skill costs. A description sits in every session that has the skill installed; the body loads only when the skill fires. `just vendor` copies the skills into `eval/scaffold/.agents/skills/`, and `just check` fails when that copy drifts from the source. ## License MIT. See `LICENSE`. The files in `docs/static/` are the exception: the baskingspot name, mark, and logos are all rights reserved. See `docs/static/LICENSE`. ````