olafkfreund/nix-skills/home-manager

Home Manager

Read the repository instructions, flake inputs, target host, imports, and existing Home Manager modules before editing. Preserve the project's module and feature-flag conventions.

Find the installation mode first

How Home Manager is installed decides which instructions apply and how changes take effect:

If the signs are ambiguous, ask rather than guess. A standalone example is not a reason to change a module-based setup, or the reverse. For nix-darwin itself, use the nix-darwin skill if it is installed, or the nix-darwin documentation.

Configure

Use configuration for user settings and package placement, dotfiles for managed files, modular services for service modules, and writing modules when extending Home Manager.

Keep home.stateVersion stable unless deliberately performing a migration. Prefer existing programs, services, home.packages, home.file, and xdg.configFile options over custom generation.

Apply, update and roll back

Apply changes through the system manager that owns Home Manager in this mode. That is the NixOS or nix-darwin rebuild for module installs, and never home-manager switch for them. See updating and rollbacks.

Switching, rolling back, expiring generations and updating inputs change the user's environment. Propose them with the exact command, and run them only with the user's authorization.

Check the user's actual Home Manager revision before relying on version- specific options. Validate the flake and use a dry build before deployment.

Nix style

• Never search /nix/store (for example find /nix/store/*foo-* -name libfoo.so)

and never copy a literal store path. Find the providing package with nix-locate, and refer to it through Nix: ${pkgs.foo}/lib or lib.makeLibraryPath [ pkgs.foo ].

• Do not quote attribute names that are valid identifiers

([A-Za-z_][A-Za-z0-9_'-]*, dashes included). Write pkgs.foo-bar and packages.x86_64-linux, not pkgs."foo-bar". Quote only other names (".config/foo", "2.0"), the keywords assert else if in inherit let or rec then with, and interpolations ("${name}"). Upstream examples in references sometimes quote needlessly; do not copy that style.