Nix-Vibe/.github/skills/nix-flake-rebuild/SKILL.md

name, description, argument-hint

name	description	argument-hint
nix-flake-rebuild	Validate Nix Flake changes end-to-end: stage, check, dry-build, and commit. Use after ANY change to .nix files, flake inputs, or module imports. Use when the user asks to apply, test, validate, rebuild, or commit NixOS config changes.	[hostname]

Nix Flake Rebuild Validation

When to Use

• After ANY modification to .nix files, flake.nix, or module imports
• Before applying configs with nixos-rebuild switch
• When the user asks to "test", "validate", "rebuild", or "apply" changes
• After adding new files, modules, or hosts

Critical Pre-Check: Git Staging

Nix flakes ONLY see Git-tracked files. If you created new files or directories, you must stage them first:

git add <new-file> <new-directory/>

Failure to do this will cause nix flake check to fail with confusing "file not found" errors.

Procedure

1. Sync Documentation (if needed)

If software was added/removed or a host role changed, update the software inventory table and host overview in README.md.

2. Stage ALL Changes

git add -A

This ensures flake evaluation can see every file.

3. Format Code

nixpkgs-fmt .

4. Run Flake Check

nix flake check

Fix any errors before proceeding. Common issues:

• Missing git add on new files
• Deprecated NixOS/Home Manager options
• Syntax errors in .nix files

5. Dry-Build for Affected Hosts

nixos-rebuild dry-build --flake .#<hostname>

Run for EACH host affected by the changes. If unsure which hosts are affected, run for all. Generate the host list dynamically from the flake so new hosts are never missed:

for host in $(nix eval .#nixosConfigurations --apply 'attrs: builtins.concatStringsSep " " (builtins.attrNames attrs)' --raw); do
  echo "=== $host ==="
  nixos-rebuild dry-build --flake .#$host || break
done

6. Commit (only if ALL checks pass)

git commit -m "descriptive message"

Do NOT commit if nix flake check or any dry-build failed.

Host Reference

Informational only — the dry-build loop above generates the host list dynamically and is authoritative. Keep this table roughly in sync when adding hosts (used to check which overlay a host gets).

Host	Type	Overlay
x1carbon	Desktop/laptop	Full (overlays: CUDA/NDI/stable)
caitlin-x1	Desktop/laptop	desktopOverlays
x470	Desktop/laptop	desktopOverlays
mary-x270	Desktop	desktopOverlays
richmond-server	Server	serverOverlays
homeserver-1	Server	serverOverlays
mcf-server	Server	serverOverlays
mcf-stream	Desktop/laptop	desktopOverlays
hp-laptop	Desktop/laptop	desktopOverlays

Post-Validation

After a successful commit, to actually apply:

# Local
sudo nixos-rebuild switch --flake .#<hostname>

# Remote
nixos-rebuild switch --target-host <user@host> --flake .#<hostname> --use-remote-sudo