OpenParable
Skip to content
← Back to skills

Writing Nix Config

Development
writing-nix-config

Writing 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. 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

RuleWhy
Run update after changesNothing takes effect until rebuilt
Run git add before nix flake checkFlakes only see git-tracked files
Use lib.fakeHash for unknown hashesNix will tell you the real hash on build failure

Common Mistakes

WrongRight
Running nix flake check on new files without git addgit add <file> first
Editing config and expecting immediate effectRun update to rebuild
Guessing SHA256 hashesUse lib.fakeHash, build, copy real hash from error
Adding package only to overlayAlso 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

HostPlatformNotes
ninuanmacOSPrimary dev, Aerospace WM
ultravioletNixOSHeadless server
bluedesertNixOSHeadless server
echelonNixOSHeadless server