| name | nix-darwin-reference |
| description | This skill should be used when editing nix-darwin or Darwin-specific Nix configuration in this dotfiles repo, troubleshooting darwin-rebuild failures, looking up macOS module options, bootstrapping a Mac with Lix/Nix, or using legacy nix-build during nix-darwin work.
|
nix-darwin reference workflow
Use this skill for Darwin/macOS Nix work in this repo. Keep it out of the global agent rules: this is reference workflow, not behavior that belongs in every prompt.
First checks
- Verify the host before host-specific rebuilds or Darwin/NixOS decisions:
hostname and uname -a.
- Edit repo sources, not generated targets. Runtime files under
~/.config, ~/.claude, ~/.pi, and similar paths are usually Nix-store symlinks.
- Prefer repo wrappers for validation:
hey check for current Darwin host, hey re or full darwin-rebuild for local rebuilds.
- Avoid generic
nix flake check on macOS in this repo because it evaluates NUC outputs and can hit known cross-system noise.
Primary references
Use the narrowest reference that answers the question:
Option lookup order
- Use local docs first when available:
darwin-help for browser-based reference.man 5 configuration.nix for terminal lookup.
- Use the online nix-darwin reference when local docs are unavailable or stale.
- Search this repo for existing patterns before adding a second convention.
- Use source-level nix-darwin docs only when option reference docs are not enough.
Install notes
- nix-darwin requires a Nix implementation; Nix and Lix are both supported.
- The nix-darwin README recommends the Lix installer because the official Nix installer has no automated uninstaller, manual macOS uninstallation is complex, and Lix supports both flake-based and channel-based setups.
- The installer does not decide which Nix interpreter the system uses later: nix-darwin manages the Nix installation by default and defaults to upstream Nix. To keep Lix, set
nix.package = pkgs.lix in configuration.
- Flake-based nix-darwin installs use
darwin-rebuild switch; before darwin-rebuild is installed, bootstrap with sudo nix run nix-darwin/<branch>#darwin-rebuild -- switch.
nix-build notes
Use nix-build only when a legacy/channel workflow needs it. Prefer nix build or repo wrappers for normal flake work.
Important details from the Nix manual:
nix-build is distinct from nix build; use man nix3-build or nix build --help for the modern command.- Successful
nix-build creates result symlinks by default, which become GC roots until removed.
--no-out-link avoids creating the symlink and GC root.- Common useful flags:
-A/--attr, --arg, --argstr, --dry-run, --out-link.
