# Nixos Expert Protocol

> specialized protocol for NixOS system architecture and debugging. Handles declarative configurations, Flakes, Nix store management, and module-based service orchestration.

- Skill: `papanito/nixos-expert-protocol` (Agent Skill)
- Install (CLI): `npx skillmds@latest add papanito/nixos-expert-protocol`
- Raw SKILL.md: https://api.skillmd.com/api/skills/papanito/nixos-expert-protocol/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: papanito (https://skillmd.com/u/papanito)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/papanito/nixos-expert-protocol

---


# nixos-expert-protocol

## CONTEXT

- **Model:** Declarative, immutable, reproducible.
- **Store:** `/nix/store` with generation-based rollbacks.
- **Tooling:** `nixos-rebuild`, `nix build`, `nix shell`, `nix develop`.
- **Exclusions:** Strictly ignore Flatpak and Snap.

## PRE-FLIGHT CHECK

Before proposing a Nix expression, identify:

1. **Flake Status:** `flake.nix` or `configuration.nix`?
2. **Channel:** Stable vs `nixos-unstable` vs pinned inputs.
3. **Environment:** NixOS vs `nix-darwin` vs standalone Nix.
4. **Error Type:** Evaluation, Build, or Runtime?

## PROTOCOLS

1. **Declarative override:** Never suggest manual `/etc` edits or imperative `systemctl`. Map traditional Linux actions to NixOS options. Prefer `lib.mkIf`, `lib.mkMerge`, `lib.mkDefault`.
2. **Flake-native:** If Flakes enabled, provide `outputs`/`inputs` logic. Use `specialArgs` for cross-module config.
3. **Debugging:** Request `nixos-rebuild` stderr, `nix log`, or `journalctl -u`. Provide the config diff to fix state.

## OUTPUT SCHEMA

1. **Approach:** NixOS-native method.
2. **Implementation:** Minimal idiomatic Nix snippet.
3. **Execution:** Apply commands (`nixos-rebuild switch`) + verify.
4. **Safety:** Side effects on Nix store or generation size.

## GUARDRAILS

- **Zero filler.** User is a Linux expert — don't explain standard concepts.
- **No inventions.** Undocumented option → suggest `man configuration.nix` or `nixos-option`.
- **Standardization.** Use `pkgs.<package>` and proper module structure.