~/.dotfiles/agents/skills/nixos-configurations/SKILL.md

SKILL.md

name	nixos-configurations
description	Use for NixOS configuration work in /persist/nix-config: flakes, dendritic layout, package sets, scripts outside .nix, Go/go run instead of Python, host/container/service patterns, and gated verification.

NixOS Configurations

Use this skill for NixOS host, container, LXC, Home Manager, module, overlay, package-set, service, build, deploy, and Nix documentation work in this repository.

Operating Rules

• Use flakes only. Treat flake.nix as the source of truth for configurations and package sets.
• Prefer dendritic configuration: small directories, default.nix entrypoints, narrow modules, and local manifests or fleet metadata when they already fit.
• New configurations must use dendritic style. For existing configurations, prefer dendritic extensions, but do not reshape or reorganize them unless the operator explicitly asks.
• Inspect live files before adding services, users, secrets, queues, bridges, containers, sidecars, agents, or workflows. Extend the existing model minimally.
• Split scripts out of .nix files. Colocate scripts with the module that owns them and wire them with builtins.readFile, writeShellScript, writeShellApplication, or a package.
• Do not use Python. When Python would normally be expected, use Go or go run; prefer go run when it avoids package or compile ceremony.
• Use 2-space Nix indentation, trailing semicolons, logical attr ordering, no unused bindings, and kebab-case filenames.

Local Shape

• Shared NixOS logic lives under modules/features/*.
• Reusable system shapes live under modules/roles/*.
• Keep hosts/<host>/default.nix thin: roles, hardware, storage, networking, and host-local services.
• Home Manager composes home-manager/features/*; prefer explicit host feature flags over hostname branching.
• Keep LXC configs in lxc/, with one system per config. New LXC systems must be defined in flake.nix, import modules/roles/lxc-base.nix, mount this repo read-only at /etc/nixos, use a dedicated /config, and avoid interactive behavior.
• For cloud, preserve the manifest style in hosts/cloud/services/manifest.nix, hosts/cloud/services/default.nix, and hosts/cloud/containers/fleet.nix.
• For containers, prefer existing common modules such as common.nix, common-podman.nix, and container-sops.nix where they apply.

Package Sets And Sources

• Do not change the buildPackageSet contract in flake.nix; it defines stable, unstable, and default.
• Modules receive pkgs, spkgs, and upkgs; prefer pkgs unless the version source matters.
• Register overlays through overlays/default.nix; keep overlays pure and shaped as final: prev:.
• Use niv for pinned non-flake sources in overlays/nix/sources.json and overlays/nix/sources.nix. Update pins with niv, and consume evaluated sources through the flake or narrow arguments rather than repeated fetchers.
• Keep Neovim plugins in overlays/nvim-overlays.nix with vimUtils.buildVimPlugin and niv sources.

Services, Secrets, And State

• Stateless services should follow docs/adr/ADR-001-General-Ephemeral-Service-Pattern.md.
• Prefer RuntimeDirectory or strictly managed paths for state.
• Use LoadCredential for service secrets.
• Use ExecStartPost when service state must be restored on every start.
• Do not add sops-nix.service as an after, requires, or wants dependency in units or modules.
• Use sops-nix and rbw for secrets. Before rbw, run rbw unlocked; if it is not OK, stop and report that rbw is locked.
• Keep durable service state reconstructable from committed configuration, encrypted secrets, and documented operator inputs.

Build And Deploy References

The verification gate in AGENTS.md controls whether these may be run.

• Host deploy: sudo nixos-rebuild switch --flake .#<hostname>.
• LXC/container build: nix build .#nixosConfigurations.<container-name>.config.system.build.toplevel.
• ISO build: nix build .#iso_x86.
• OpenWrt: ./images/openwrt-vm/update-ow-feeds.sh, then nix build .#packages.x86_64-linux.ow-vm-image.
• cloud rebuild source: cd /persist/nix-config/nx-ago-testing && sudo nixos-rebuild switch --flake .#cloud.
• In hosts/cloud/, just update and just deploy wrap that same rebuild. Use just secrets for secret management.
• Do not use /persist/deploy/nix-config, target-local prepared checkouts, or deploy markers as a normal cloud rebuild source.

Documentation Lookup

For NixOS, Home Manager, package, and Nix language documentation search, call the NixOS reference MCP directly:

mcp-cli call nixos-reference nix \
  '{"action":"search","query":"systemd.services","type":"options","limit":20}'
mcp-cli call nixos-reference nix \
  '{"action":"search","query":"programs.zellij","source":"home-manager","limit":20}'
mcp-cli call nixos-reference nix \
  '{"action":"search","query":"tutorials/nix-language","source":"nix-dev","limit":20}'