nix-best-practices

Manage Nix flake inputs and overlays to prevent duplicate nixpkgs downloads.

Updated Aug 23, 2026
One-click install
npx skills add https://github.com/awfixers-stuff/opencode-config --skill nix-best-practices-awfixers-stuff
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: nix-best-practices
Source: https://github.com/awfixers-stuff/opencode-config/tree/main/skills/nix-best-practices
Command: npx skills add https://github.com/awfixers-stuff/opencode-config --skill nix-best-practices-awfixers-stuff

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill captures patterns and practical guidance to avoid common Nix flakes and overlay pitfalls, such as duplicate nixpkgs downloads, misapplied overlays, unfree package handling issues, and misconfigured development shells.

Core Features & Use Cases

  • Flake organization: shows a standard flake.nix layout and how to list inputs in outputs to prevent "unexpected argument" errors.
  • Overlay management: explains using follows to chain nixpkgs across overlays and how to apply overlays when importing nixpkgs.
  • Unfree packages & binary overlays: describes options for unfree packages, creating binary-overlay repos, and obtaining correct SHA256/SRI hashes.
  • Dev shell & direnv patterns: documents devShell setup, environment handling, and direnv integration for reproducible developer environments.

Quick Start

Update your flake inputs with nix flake update, ensure all overlay inputs set inputs.nixpkgs.follows to a single nixpkgs source, and verify overlays are included when importing nixpkgs.

Frequently Asked Questions about nix-best-practices

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I prevent duplicate nixpkgs downloads when using flakes and overlays?▼

Prevent duplicate nixpkgs downloads by setting inputs.nixpkgs.follows across all overlay inputs to point to a single nixpkgs source. This ensures your flake configuration shares one dependency tree instead of fetching multiple redundant copies.

Why does my nix flake throw an unexpected argument error in the outputs?▼

An unexpected argument error in nix flake outputs usually occurs when inputs are not properly listed in the outputs function signature. Applying a standard flake.nix layout ensures all declared inputs are correctly passed and available to the configuration.

What is the best way to apply overlays when importing nixpkgs?▼

The best way to apply overlays when importing nixpkgs is to pass them directly during the pkgs import process. This guarantees that the custom packages or modifications defined in your overlays are available in the resulting package set.

How do I handle unfree packages in a nix dev shell?▼

To handle unfree packages in a nix dev shell, use nixpkgs-unfree or adjust your user configuration to explicitly permit unfree software. This allows the environment to successfully build and include proprietary packages without errors.

Does direnv work with nix flakes for reproducible dev shells?▼

Yes, direnv works with nix flakes to create reproducible dev shells by automatically loading the environment when you enter the project directory. Integrating direnv with your devShell setup ensures consistent developer environments without manual activation.

How do I get the correct SHA256 or SRI hash for a binary overlay repository?▼

To get the correct SHA256 or SRI hash for a binary overlay repository, use the standard nix fetching mechanisms which output the expected hash upon evaluation. This ensures your binary overlays are securely and correctly imported into your project.