Writing Nix Config
Developmentwriting-nix-configWriting Nix Config is an Agent Skill for development published in the joshsymonds/nix-config repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Patterns for this nix-config flake repository. Use when editing .nix files, adding packages, creating modules, or debugging flake issues.
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/joshsymonds/nix-config/blob/HEAD/home-manager/claude-code/skills/nix-patterns/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/writing-nix-config, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Nix Configuration Patterns
Critical Rules
| Rule | Why |
|---|---|
Run update after changes | Nothing takes effect until rebuilt |
Run git add before nix flake check | Flakes only see git-tracked files |
Use lib.fakeHash for unknown hashes | Nix will tell you the real hash on build failure |
Common Mistakes
| Wrong | Right |
|---|---|
Running nix flake check on new files without git add | git add <file> first |
| Editing config and expecting immediate effect | Run update to rebuild |
| Guessing SHA256 hashes | Use lib.fakeHash, build, copy real hash from error |
| Adding package only to overlay | Also add to pkgs/default.nix |
Commands
update # Rebuild current system
nix flake check # Validate flake
nix build .#<package> # Build package
nix eval .#nixosConfigurations.<host>.config.<option> # Check config value
Package Pattern
# pkgs/<name>/default.nix
{ lib, stdenv, fetchFromGitHub, ... }:
stdenv.mkDerivation rec {
pname = "name";
version = "1.0.0";
src = fetchFromGitHub {
owner = "...";
repo = "...";
rev = "v${version}";
hash = "sha256-AAAA..."; # Use lib.fakeHash first, nix will tell you real hash
};
meta = with lib; {
description = "...";
license = licenses.mit;
platforms = platforms.all;
};
}
Then add to pkgs/default.nix and overlays/default.nix.
Home Manager Module Pattern
# home-manager/<app>/default.nix
{ pkgs, lib, ... }: {
home.packages = [ pkgs.app ];
# Or use programs.<app> if module exists
programs.app = {
enable = true;
settings = { ... };
};
}
Then import in home-manager/common.nix or platform-specific file.
Agenix Secret Pattern
# 1. Add to secrets/secrets.nix
"secrets/hosts/<host>/<name>.age".publicKeys = keys.<host>;
# 2. Declare in host config
age.secrets."<name>" = {
file = ../../secrets/hosts/<host>/<name>.age;
owner = "<service-user>";
mode = "0400";
};
# 3. Create the secret
agenix -e secrets/hosts/<host>/<name>.age
This Repo's Systems
| Host | Platform | Notes |
|---|---|---|
| ninuan | macOS | Primary dev, Aerospace WM |
| ultraviolet | NixOS | Headless server |
| bluedesert | NixOS | Headless server |
| echelon | NixOS | Headless server |