# using zigman in practice

zigman puts the [Zig language reference](https://ziglang.org/documentation/master/) 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](https://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](https://tangled.org/zzstoatzz.io/zigman).