agentleFS
VercelKnown publishervercel-labs/fx/.fx/skills/zig/SKILL.md

zig

Skill3.9k starsChanged 9 days agoApache-2.0View on GitHub

Write, review, refactor, and upgrade Zig 0.17 code (0.17.0 and 0.17.1) with correct ownership, error sets, I/O, concurrency, tests, and build modes, and without removed, deprecated, or silently changed 0.17 APIs. Use for any .zig or build.zig edit; for allocator, lifetime, error-set, std.Io, thread, fuzzing, ReleaseSafe or ReleaseFast, and binary size questions; when 0.16 code fails on 0.17, or 0.17 code fails on 0.16 with errors such as "no field or member function named 'print'"; when replacing std.fmt.allocPrint, bufPrint, std.mem.indexOf, copyForwards, std.fs.path, builtin.os, DebugAllocator, or @intFromEnum; when `**`, errdefer captures, @cImport, or @hasDecl behave differently; when migrating 0.16 code, merging an upgraded main into a 0.16 branch, or installing 0.17 next to another Zig; when asked what 0.17 or 0.17.1 changed, fixed, or still breaks; or when the user invokes $zig.

9 other projects use a version of this.

Adopted by

Steady: 0 new projects took it in the last 4 weeks, none the 4 weeks before.thin data

Week of Sep 20: 0 new projectsWeek of Sep 27: 0 new projectsWeek of Oct 4: 0 new projectsWeek of Oct 11: 0 new projectsWeek of Oct 18: 0 new projectsWeek of Oct 25: 0 new projectsWeek of Nov 1: 0 new projectsWeek of Nov 8: 0 new projects
Sep 2026Oct 2026Nov 2026
New projects taking a version of this file each week, over the 8 weeks our latest run read: only 0 in all, so this is a hint, not a trend.

Most recently taken up by

Who's talking about vercel-labs/fx

The biggest 5 of 37 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 37

Talked about on GitHub, Bluesky and Hacker News (37 times).

On GitHub · 32

27 more on GitHub

On Hacker News · 2

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. 0 are common, 7 are distinctive, and 7 are very specific to this project.

  • 0

    Common

    Most of the 6 edited versions we read keep these.

  • 7

    Distinctive

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read .minimum_zig_version in build.zig.zon and run zig version.

    line 33
  2. Very specific:

    0.16 on a 0.17 project: do not build with it. It reports correct code as broken (no field or member function named 'print' in …

    line 36
  3. Very specific:

    Never upgrade, relink, or replace a shared zig.

    line 47
  4. Distinctive:

    Before editing, map the contract: ownership, borrowing, lifetimes, allocation, errors, external bounds, thread ownership, and build-mode …

    line 52
  5. Distinctive:

    Every allocation has one owner and a cleanup path on success and failure.

    line 60
  6. Distinctive:

    No pointer or slice outlives its storage or survives a mutation that can reallocate it.

    line 61
  7. Very specific:

    std.mem.eql and findDiff on floats: no longer treat a slice as equal to itself (NaN is not equal to NaN).

    line 88
  8. Distinctive:

    New code: use only the right-hand columns above, and before reporting it done, require exit 0 from the scanner (no finding to fix, every …

    line 168
  9. Distinctive:

    Read toolchain first if CI, release targets, or OS minimums change.

    line 177
  10. Very specific:

    Run check_deprecated.py --review, replace what remains, and read every review hotspot against the six behavior changes above.

    line 192
  11. Distinctive:

    Add a test for each silent change you fix, so a later merge cannot undo it, and report anything left deprecated on purpose.

    line 195
  12. Very specific:

    Reviewing: run the scanner on the changed files, and treat a new @hasDecl probe, containsAtLeastScalar call, or @bitCast of an array, …

    line 202
  13. Very specific:

    Use the repository's commands first.

    line 211
  14. Distinctive:

    Add only what the claim needs: a fuzz target when parsing or untrusted bytes changed, Debug and ReleaseSafe when safety checks could …

    line 213

“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Zig 0.17

What Zig 0.17.x changed, and the rules that keep Zig correct under failure, concurrency, and later change. The facts were checked against the 0.17.0 and 0.17.1 standard library and compiler and a real 0.16 to 0.17 port. Trust them and the bundled scripts; read std source only for an API this skill lacks.

Repository instructions (AGENTS.md and similar), build.zig, and build.zig.zon come first and override this skill. Keep established patterns unless they cause a correctness, safety, or ownership defect. For another Zig release, use only the version-independent references and check std in its source.

Check the compiler first

Read .minimum_zig_version in build.zig.zon and run zig version. Neither 0.16 nor 0.17 enforces that field, so a wrong compiler fails late and misleadingly.

  • 0.16 on a 0.17 project: do not build with it. It reports correct code as broken (no field or member function named 'print' in 'mem.Allocator', no field named 'debug' in enum 'builtin.OptimizeMode'); never "fix" that back to 0.16 names. Find a 0.17 compiler with which -a zig and in versioned install directories, and run it by absolute path or PATH=<dir>:$PATH.
  • 0.17.0 and 0.17.1: the language and LLVM 22.1.8 are the same, but 0.17.1 fixes miscompilations, changes a few std signatures, and changes two behaviors silently: ending a std.http request that sent a body now reads its unread answer to the end, and -femit-llvm-bc is now optimized. Build and test with the pinned patch release; toolchain lists what 0.17.1 fixed and still breaks.
  • Never upgrade, relink, or replace a shared zig. Install a missing release next to the others, or ask, and say which checks did not run on it.

Working method

Before editing, map the contract: ownership, borrowing, lifetimes, allocation, errors, external bounds, thread ownership, and build-mode assumptions. Make invalid states hard to express with enums, tagged unions, optionals, and named error sets. Keep allocation, blocking I/O, mutation, and ownership transfer visible in signatures or doc comments. Make the smallest coherent change, and do not widen a shared contract for one caller. These are correctness issues, not style:

  • Every allocation has one owner and a cleanup path on success and failure.
  • No pointer or slice outlives its storage or survives a mutation that can reallocate it.
  • External lengths, offsets, counts, recursion, retries, queues, and captured output are validated and bounded before arithmetic, allocation, or slicing.
  • Assertions and catch unreachable guard program-owned invariants only; malformed external data gets normal error handling in every build mode.
  • Integer conversions and arithmetic have stated range and overflow reasoning.
  • Shared mutable state has an owner and a synchronization policy, and cancellation or shutdown leaves no thread or resource behind.
  • Public contracts state ownership and do not expose anyerror, anytype, or internal mutable storage by accident.

Changes that compile but change behavior

A clean build proves none of these. Check every one during a migration.

  1. @hasDecl only sees pub declarations, even in the same file, so a probe of a private one silently turns a feature off. Make it pub.
  2. std.mem.containsAtLeastScalar(T, list, element, minimum) swapped its last two parameters (0.16: minimum, element); old u8 calls compile and answer wrongly. Slice containsAtLeast keeps (haystack, count, needle).
  3. @bitCast was redefined. Array and vector casts concatenate logical bit representations (endian-agnostic). extern struct/extern union operands are rejected; pun through @as(*align(1) const T, @ptrCast(&value)). A cast to an enum safety-checks the tag.
  4. @tagName(builtin.optimize) yields debug, safe, fast, small; map it when a user sees the label.
  5. std.mem.eql and findDiff on floats no longer treat a slice as equal to itself (NaN is not equal to NaN).
  6. std.array_list.Managed (and so std.json.Array) has a required pointer_stability field: use .init(gpa) or .fromOwnedSlice(gpa, items).

Removed: these no longer compile

0.160.17
[1]T{v} ** n, "ab" ** nconst a: [n]T = @splat(v);; repeated strings need a comptime helper (language)
errdefer |err| ...Split the function and handle the error in the caller
void{}, i0{}, u0
@cImportThe translate-c package (build system)
opt == .ReleaseSafe and the other old tags in == or !=.debug, .safe, .fast, .small
std.heap.StackFallbackAllocator, stackFallbackstd.heap.BufferFirstAllocator.init(buffer, fallback)
@typeInfo(T).@"struct".fields.field_names, .field_types, .field_attrs, .decl_names
b.build_root, if (b.args) |a| run.addArgs(a)b.root (a Cache.Path), run.addPassthruArgs()

The full list, with std.ascii, bit sets, packed ints, and ZON, is in std.

Deprecated: still compiles, do not write it

DeprecatedUse
std.fmt.allocPrint(gpa, f, a)gpa.print(f, a) (same error set)
std.fmt.bufPrint, bufPrintSentinel, BufPrintErrorstd.mem.print, std.mem.printSentinel, std.mem.PrintError
std.mem.indexOf*, lastIndexOf*std.mem.find, findScalar, findAny, findPos, findLast, findScalarLast, findLastAny
std.mem.copyForwards(T, d, s), copyBackwards@memmove(d[0..s.len], s); @memmove requires equal lengths
anything in std.fsstd.Io.Dir.path, std.Io.Dir.max_path_bytes, std.Io.Dir.max_name_bytes
path.resolve, path.relativestd.Io.Dir.path.resolveAlloc, relativeAlloc
@import("builtin").os, .cpu, .abi, .object_formatbuiltin.target.os, .target.cpu, .target.abi, .target.ofmt
builtin.mode, std.debug.runtime_safetybuiltin.optimize, builtin.optimize.runtimeSafety()
std.builtin, std.lang.OptimizeModestd.lang, std.lang.Optimize
@intFromEnum, @enumFromInt@backingInt, @fromBackingInt (zig fmt rewrites them)
std.ArrayListUnmanaged, *ArrayHashMapUnmanaged, *BitSet*std.ArrayList, std.array_hash_map.String/Auto/Custom, std.bit_set.Integer/Array/Static/Dynamic
list.getLast(), getLastOrNull()list.last().?, list.last()
std.heap.DebugAllocator (deprecated)std.heap.SafeAllocator
std.unicode.utf8DecodeValidate with utf8ByteSequenceLength, then utf8Decode2/3/4
std.meta.fieldNames, fieldInfo, fieldTypes@typeInfo
Run addArtifactArg, addFileArg, addPrefixed*Arg, ...addArtifactArg2(x, .{ .prefix = "-p" }), addFileArg2, ...
b.addTranslateCThe translate-c package

Most rows forward to their replacement, so the rename cannot change behavior. Three can: copyForwards (lengths), utf8Decode (validation), and DebugAllocator, which is not an alias of SafeAllocator. Rarer deprecations are in std.

Entry point, I/O, and allocators

pub fn main(init: std.process.Init) !void {
    const greeting = try init.gpa.print("hello, {s}", .{"zig"});
    defer init.gpa.free(greeting);
    var buffer: [4096]u8 = undefined;
    var stdout = std.Io.File.stdout().writer(init.io, &buffer);
    try stdout.interface.print("{s}\n", .{greeting});
    try stdout.interface.flush();
}
  • init.gpa is a std.heap.SafeAllocator in Debug and ReleaseSafe builds and reports leaks when main returns, without changing the exit code. Other builds get std.heap.c_allocator when linking libc and smp_allocator otherwise. Do not hand-build that switch.
  • init.io is a std.Io.Threaded: pass it down instead of creating another. init.arena lives until exit; init.environ_map and init.minimal.args hold the environment and arguments. pub fn main() !void gets neither.
  • Pick allocators by lifetime: std.testing.allocator in tests, SafeAllocator for leak checks (never in production: it never reuses memory), an ArenaAllocator per request or batch, FixedBufferAllocator for bounded scratch, and std.heap.smp_allocator for shared concurrent use.
  • std.Io.Evented does not compile on 0.17.0 or 0.17.1; use std.Io.Threaded.
  • std.ArrayList(T) starts as .empty and takes the allocator per call. Growth can move storage: take interior pointers after reserving capacity.
  • Reading undefined is illegal behavior. Narrow with std.math.cast; use @intCast only after the range is proven. Locks, Child.Term, and cancellation are in io-concurrency-security.

Writing, migrating, and reviewing

New code: use only the right-hand columns above, and before reporting it done, require exit 0 from the scanner (no finding to fix, every path read):

python3 <this skill>/scripts/check_deprecated.py <files or directories>

Migrating 0.16 code:

  1. Read toolchain first if CI, release targets, or OS minimums change.
  2. Apply the mechanical renames, then let zig fmt (0.17) rewrite @intFromEnum and @enumFromInt:

    python3 <this skill>/scripts/migrate.py --write <files or directories>
    zig fmt <files or directories>

    scripts/migrate.py only makes exact forwarding renames outside strings and comments, prints a NOTE where judgment is needed, never writes through a link, and without --write only reports.

  3. Zig analyzes lazily: build every artifact the project ships and run the full test suite.
  4. Run check_deprecated.py --review, replace what remains, and read every review hotspot against the six behavior changes above. Rewrite each copyForwards site by hand, trimming the destination to s.len.
  5. Add a test for each silent change you fix, so a later merge cannot undo it, and report anything left deprecated on purpose.

Merging an upgraded main into a 0.16 branch: merge, do not rebase. Take main's side where a conflict differs only in 0.16 spellings; keep the branch's behavior changes, written the 0.17 way. Then run steps 2 to 4 on the result.

Reviewing: run the scanner on the changed files, and treat a new @hasDecl probe, containsAtLeastScalar call, or @bitCast of an array, extern struct, or enum as a question. Rank memory safety, illegal behavior, races, and leaks first, then contracts, then maintainability, then measured speed or size. Correctness findings block; design alternatives are considerations with their tradeoff.

Verification gate

Use the repository's commands first; otherwise run zig fmt --check on the project's Zig paths, zig build, and zig build test with the pinned compiler. Add only what the claim needs: a fuzz target when parsing or untrusted bytes changed, Debug and ReleaseSafe when safety checks could matter, a cross-compile for portability, ReleaseFast or ReleaseSmall for their speed or size, and the built executable for runtime claims. Say what could not run.

References

Load one only when the task needs more than this file:

  • types-memory-errors: data models, allocators, lifetimes, error sets, arithmetic, casts, generics, state machines.
  • api-maintainability: public APIs, module boundaries, naming, documentation, refactors.
  • io-concurrency-security: std.Io, files, sockets, subprocesses, paths, threads, locks, atomics, external input.
  • testing-build-size: tests, fuzzing, build modes, dependencies, performance, binary size.
  • language: 0.17 casts, builtins, comptime, reflection, and removed syntax, with before and after code.
  • std: exact 0.17 signatures, allocators, containers, ZON, rare deprecations.
  • build-system: build.zig, build.zig.zon, packages, translate-c, editor tooling.
  • toolchain: installing a Zig next to another, CI, targets, OS minimums, what 0.17.1 fixed and still breaks, port gotchas.
  • examples.zig: compile-checked snippets; zig test references/examples.zig passes on 0.17.0 and 0.17.1.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.