1---2name: nix3description: Nix language, flakes, NixOS, Home Manager, and agent-skills packaging. TRIGGER when: working with .nix files, flake.nix, flake.lock, Nargo.toml (Nix packaging context), NixOS configuration, Home Manager modules, nix-agent MCP tools, agent-skills-nix deployment, or rigup.nix riglets. DO NOT TRIGGER when: only using nix PATH (chezmoi handles that), or working on ZK circuits (use noir skill), or Nix language is incidental to another domain.4---56# nix78Practical patterns for the Nix ecosystem: the language itself, flake9architecture, NixOS/Home Manager configuration, package building, and the10emerging pattern of packaging AI agent skills as Nix derivations.1112## What You Get1314- Nix language idioms (let/with/inherit, builtins, lazy evaluation)15- Flake architecture (inputs, outputs, lockfiles, overlays)16- NixOS and Home Manager module patterns17- Package builders (mkDerivation, buildGoModule, buildNpmPackage)18- Agent-skills-as-Nix-packages patterns (rigup, nix-agent MCP)1920## When to use2122- Writing or reviewing `.nix` files (flakes, modules, overlays, packages)23- Configuring NixOS or Home Manager24- Building Nix packages (mkDerivation, buildGoModule, buildNpmPackage, etc.)25- Managing Nix profiles and registries26- Packaging agent skills for Nix-based deployment (agent-skills-nix, rigup)27- Using nix-agent MCP tools for NixOS automation2829## When NOT to use3031- Nix PATH setup in chezmoi -- handled by `paths.zsh.tmpl` and `chezmoi.toml`32- ZK circuit design -- use noir skill33- Solidity or Ethereum -- use solidity-auditor or ethskills3435## Reading guide3637| Working on | Read |38| --------------------------------------------------------------------- | --------------------------------------------------------------- |39| Nix language idioms, builtins, let/with/inherit | [references/language](references/language.md) |40| Flake structure, inputs, outputs, lockfiles | [references/flakes](references/flakes.md) |41| NixOS modules, options, services | [references/nixos](references/nixos.md) |42| Home Manager config, programs, activation | [references/home-manager](references/home-manager.md) |43| Building packages (mkDerivation, language builders) | [references/packaging](references/packaging.md) |44| Nix profiles, registries, nix-env alternatives | [references/profiles](references/profiles.md) |45| Agent skills as Nix packages (agent-skills-nix, rigup, nix-agent MCP) | [references/agent-integration](references/agent-integration.md) |4647## Key principles48491. **Reproducibility first** -- pin inputs, use flake.lock, avoid impure operations502. **Composition over mutation** -- overlay and override, never patch in place513. **Lazy evaluation** -- Nix is lazy; structure code to exploit this524. **Declarative over imperative** -- describe the target state, not the steps535. **Module system is the API** -- options with types, defaults, and docs5455## Common pitfalls5657| Mistake | Fix |58| --------------------------------------- | ------------------------------------------------------------------ |59| Using `rec { }` when `let ... in` works | `rec` pollutes scope and causes infinite recursion -- prefer `let` |60| `with pkgs;` at module level | Shadows names silently -- use `pkgs.foo` or selective `inherit` |61| Forgetting `meta.mainProgram` | Breaks `nix run` -- always set it for packages with binaries |62| `builtins.fetchurl` in flakes | Impure -- use flake inputs or `fetchurl` from nixpkgs |63| Mutable channel references | Pin nixpkgs as a flake input, not `<nixpkgs>` |64| `nix-env -i` for system packages | Use `environment.systemPackages` or `home.packages` |65| Testing with `nix-build` when flake | Use `nix build .#package` -- `nix-build` ignores flake.nix |6667## See also6869- droo-stack -- shell patterns for nix-related scripts70- chezmoi templates in droo-stack -- `paths.zsh.tmpl` nix conditionals
DROOdotFOO