nixos-best-practices_skill

Overview

This skill helps you configure NixOS with flakes and Home Manager, focusing on correct overlay placement and predictable package behavior. It clarifies the effect of home-manager.useGlobalPkgs and where overlays must be defined so package changes actually apply. Use it to structure multi-host configurations and avoid common overlay-scope mistakes.

How this skill works

The skill inspects your flakes and host configuration patterns and explains where to place nixpkgs.overlays depending on useGlobalPkgs. It highlights whether overlays should live in the system (NixOS host) files, the home-manager module args, or the per-user home.nix, and shows how to pass inputs and specialArgs. It also points out typical causes when package changes don’t appear after rebuilds.

When to use it

• Configuring NixOS with flakes and Home Manager
• You added an overlay but the package isn’t available after rebuild
• Using home-manager.useGlobalPkgs = true with custom overlays
• Organizing multiple host configurations or shared modules
• Debugging package or overlay scope problems

Best practices

• Define system-wide overlays in your NixOS host configuration (nixpkgs.overlays) when they should affect system packages
• If useGlobalPkgs = true, put overlays in the host’s home-manager.nixpkgs.overlays or the system config — not in home.nix
• Use useGlobalPkgs = false only when you need isolated user package sets
• Pass flake inputs and pkgs via extraSpecialArgs/specialArgs to modules for reproducibility
• Organize hosts/ and modules/ directories and import shared modules to avoid duplication

Example use cases

• Enable a corporate package overlay that must be available to system services and user profiles — put it in the host nixpkgs.overlays
• You set useGlobalPkgs = true and your overlay in home.nix is ignored — move overlay to host home-manager.nixpkgs.overlays
• Maintain a fleet of machines with common overlays and per-host differences using modules/ and hosts/ structure
• Fix a package not found after rebuild by verifying overlay scope vs useGlobalPkgs setting