How do I install the Nix Darwin Reference skill?

Run npx skillmds@latest add edmundmiller/nix-darwin-reference in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Nix Darwin Reference safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Nix Darwin Reference?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Nix Darwin Reference free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Nix Darwin Reference?

edmundmiller (@edmundmiller) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Nix Darwin Reference by edmundmiller

Name: Nix Darwin Reference
Author: edmundmiller

File contents

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.
Use hey check for validation and hey re for authorized local activation; raw rebuild commands are not an alternative to repository command policy.
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:

Need	Reference
nix-darwin modules/options	`darwin-help`, `man 5 configuration.nix`, or https://nix-darwin.github.io/nix-darwin/manual/index.html
nix-darwin install/bootstrap	https://github.com/nix-darwin/nix-darwin
Lix install/upgrade on macOS/Linux	https://lix.systems/install/#on-any-other-linuxmacos-system
Legacy `nix-build` behavior	https://nix.dev/manual/nix/2.34/command-ref/nix-build.html

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.

---name: nix-darwin-referencedescription: Provides nix-darwin references for macOS module options, Mac bootstrap, and Darwin rebuild failures in dotfiles.---# nix-darwin reference workflowUse 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.- Use `hey check` for validation and `hey re` for authorized local activation; raw rebuild commands are not an alternative to repository command policy.- Avoid generic `nix flake check` on macOS in this repo because it evaluates NUC outputs and can hit known cross-system noise.## Primary referencesUse the narrowest reference that answers the question:| Need | Reference || ---------------------------------- | ------------------------------------------------------------------------------------------------------ || nix-darwin modules/options | `darwin-help`, `man 5 configuration.nix`, or https://nix-darwin.github.io/nix-darwin/manual/index.html || nix-darwin install/bootstrap | https://github.com/nix-darwin/nix-darwin || Lix install/upgrade on macOS/Linux | https://lix.systems/install/#on-any-other-linuxmacos-system || Legacy `nix-build` behavior | https://nix.dev/manual/nix/2.34/command-ref/nix-build.html |## Option lookup order1. Use local docs first when available: - `darwin-help` for browser-based reference. - `man 5 configuration.nix` for terminal lookup.2. Use the online nix-darwin reference when local docs are unavailable or stale.3. Search this repo for existing patterns before adding a second convention.4. 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` notesUse `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`.

Frequently asked questions

Nix Darwin Reference