Nixos Best Practices

What it does

This skill helps AI agents configure NixOS systems using flakes, manage overlays effectively, and structure configurations for maintainability. It emphasizes following established best practices within the NixOS ecosystem, ensuring reproducible builds and optimized system setup. The skill guides users to avoid common pitfalls by referencing relevant rule files and documentation before making configuration changes.

When to use it

• Configuring NixOS with flakes and Home Manager
• Troubleshooting issues where overlays don't seem to apply correctly
• Implementing useGlobalPkgs = true with custom overlays
• Organizing NixOS configurations across multiple hosts
• Diagnosing situations where package changes aren’t appearing after a rebuild

Key capabilities

• Flakes configuration management
• Overlay scope and application understanding (particularly in relation to useGlobalPkgs)
• Structuring host configurations for organization
• Package installation best practices within NixOS
• Guidance on avoiding common configuration mistakes
• Systematic debugging approaches for NixOS issues

Example prompts

• "How do I configure overlays when using useGlobalPkgs = true?"
• "What is the correct structure for a NixOS flake configuration?"
• "I'm having trouble with an overlay not applying. What should I check?"

Tips & gotchas

• Read the documentation first: Before making any changes, review the relevant rule files (overlay-scope, flakes-structure, etc.) and common-mistakes.md.
• Overlay placement is critical: When using useGlobalPkgs = true, overlays must be defined in the NixOS configuration block, not within Home Manager files.
• Avoid guesswork: Consult documentation rather than experimenting with options or assuming functionality.