# using zigman in practice

zigman puts the Zig language reference one keystroke away — for when you're mid-edit and can't remember the exact form of a builtin, a `switch` prong, or a sentinel type, and don't want to lose your place to a browser. this is the practical playbook.

## the one habit

when you're unsure how a Zig *language* feature is spelled or behaves, look it up instead of guessing:

    zigman casting

you don't need the exact section name. type the word you have in your head — zigman resolves it to the obvious section, and only asks you to choose when it's genuinely ambiguous.

    zigman optional        # opens "Optionals"
    zigman error union     # opens "Error Union Type"
    zigman comptime        # opens "comptime"
    zigman sentinel        # ambiguous -> lists Sentinel-Terminated Arrays / Pointers / Slices

## when you don't know the word

browse or filter the table of contents, then open one:

    zigman -l              # every section, indented by depth
    zigman -l error        # just the sections about errors
    zigman labeled block   # multi-word: lists Blocks, Labeled-switch/while/for

the rule of thumb: `zigman -l <word>` to find the name, then `zigman <name>` to read it.

## everyday workflows

- **a compile error names a concept you're shaky on** — read that section first.

`zig build` complains about `@intCast` arity? `zigman @intCast` shows the current single-argument form.

- **you forget exact syntax mid-write** — `zigman for` (loop captures + index),

`zigman switch` (prongs, ranges, exhaustiveness), `zigman slices` (slicing semantics).

- **you're reviewing and want to be sure before asserting "Zig does X"** — look it up

rather than trusting memory; the reference is the source of truth.

- **you need an older release's behavior** — pin the version:

```zigman -V 0.15.1 comptime` ``

- **you'd rather see it in the browser** (full page, links, search) — open the section

there instead: ```zigman -o comptime` ``

## it composes

output is plain markdown on stdout, so pipe it anywhere:

    zigman comptime | glow -          # pretty-render
    zigman switch | rg -i "inline"     # grep within a section
    zigman -l | fzf                    # fuzzy-pick a section to read

on a terminal it pages through `$PAGER` (default `less -FRX`); piped, it stays raw.

## using zigman from an AI agent

zigman ships an agentskills.io skill at `skills/zigman/SKILL.md`. the behavior it installs is simple and high-value: *read the reference instead of guessing Zig semantics.* it works in any skills-aware harness (Claude Code, opencode, Pi, Cursor, …) — point the client at the skill directory and make sure the `zigman` binary is on PATH. the agent then runs `zigman <topic>` (via its shell tool) before writing tricky Zig, which measurably reduces version-stale guesses like the old `@intCast(u8, x)` form.

print the skill, or a shell completion, straight from the binary:

    cat "$(dirname "$(command -v zigman)")"/../skills/zigman/SKILL.md   # if installed from source
    zigman --completions zsh                                            # tab-complete section names

## what zigman is not

zigman covers the **language**, not the standard library. for `std.ArrayList`, `std.Io`, `std.fmt`, allocators, and the rest, read the std source directly — `zig env` reports `.std_dir` (a path relative to `$HOME`):

    rg --type zig 'pub fn ' "$HOME/$(zig env | sed -n 's/.*\.std_dir = "\(.*\)",/\1/p')/array_list.zig"

## install & source

`curl -fsSL https://nate.tngl.io/zigman/install.sh | sh`, or build from source with `zig build` (zig 0.16+). source and issues: tangled.org/zzstoatzz.io/zigman.