This Claude skill empowers developers to efficiently write, manage, and debug Nix expressions, NixOS configurations, and home-manager setups. It streamlines the creation of reproducible environments and Infrastructure as Code (IaC) by leveraging Nix flakes, modules, and advanced debugging techniques to ensure system consistency and reliability.

When should I use nix?

nix is useful in the following scenarios: • Automating NixOS system configurations and server deployments for reproducible infrastructure. • Managing personalized user environments and dotfiles across multiple machines using home-manager. • Developing and maintaining Nix flakes to create consistent, isolated development shells for teams. • Troubleshooting complex Nix build errors, such as infinite recursion or dependency conflicts, using specialized CLI tools and best practices. • Refactoring legacy Nix code into modular structures using the module pattern and Nixpkgs best practices.

name	nix
description	Write Nix code and manage NixOS/home-manager configurations. Use when writing Nix expressions, flakes, modules, or debugging derivations.

Nix

References

Nix Manual: https://nix.dev/manual/nix/latest/
Nixpkgs Manual: https://nixos.org/manual/nixpkgs/stable/
NixOS Manual: https://nixos.org/manual/nixos/stable/
NixOS Wiki: https://wiki.nixos.org/
home-manager Manual: https://nix-community.github.io/home-manager/
nix.dev (tutorials): https://nix.dev/
Flakes: https://wiki.nixos.org/wiki/Flakes

CLI Tools

nix-search <query>           # Package search (nix-search-cli, fast)
nix-search --name <name>     #   by package name (supports glob: 'emacsPackages.*')
nix-search --program <prog>  #   by installed program
nix-search --details <query> #   show details (description, programs, etc.)
nix-search --flakes <query>  #   search flakes instead of nixpkgs
nix flake show            # Show flake outputs
nix flake check           # Validate flake
nix repl                  # Interactive REPL
nix eval .#<attr>         # Evaluate expression
nix build .#<pkg>         # Build package
nix develop               # Enter dev shell
nix-tree                  # Dependency tree visualization
nixos-rebuild switch      # Apply NixOS config
home-manager switch       # Apply home-manager config

Workflow

Always git add new files - Flakes only see git-tracked files

MCP Servers

context7: Use mcp__context7__resolve-library-id with "nix" or "nixos" to fetch docs

Module Pattern

{ config, lib, pkgs, ... }:
let
  cfg = config.my.module;
in {
  options.my.module = {
    enable = lib.mkEnableOption "my module";
    package = lib.mkPackageOption pkgs "pkg-name" {};
  };

  config = lib.mkIf cfg.enable {
    # configuration here
  };
}

or, flat:

{
  programs.git.enable = true;
}

Best Practices

Use lib.mkIf - Not raw if for conditional config
Use lib.mkMerge - Combine multiple config sets
Avoid with pkgs; - Pollutes scope, use explicit pkgs.foo
Use lib.optionals - For conditional list items
Pin nixpkgs - Lock flake inputs for reproducibility

Anti-Patterns

import <nixpkgs> - Use flake inputs instead
Hardcoded paths - Use ${pkg} interpolation
rec { } - Prefer let ... in or recursive finalAttrs pattern
assert for user errors - Use lib.assertMsg with message

Debugging

nix repl                           # Then :l <nixpkgs>
nix eval --raw .#foo               # Print derivation path
nix log /nix/store/<hash>-foo      # Build logs
nix-store -qR <drv>                # Runtime deps
nix-store -qd <drv>                # Build deps
nix why-depends .#a .#b            # Dependency chain

Common Fixes

"infinite recursion" - Check for self-referencing rec, use let instead "attribute not found" - Check spelling, use pkgs.lib.attrNames to list "cannot coerce" - Wrap strings: "${toString val}" "IFD (import from derivation)" - Avoid in flakes, causes evaluation-time builds

nix

When & Why to Use This Skill

Use Cases

Nix