nix-tutor

Teaches the Nix language, flakes, nixpkgs packaging, and module system to beginners.

Updated Jul 4, 2023
One-click install
npx skills add https://github.com/kohdice/dotfiles --skill nix-tutor-kohdice
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: nix-tutor
Source: https://github.com/kohdice/dotfiles/tree/main/config/agents/skills/nix-tutor
Command: npx skills add https://github.com/kohdice/dotfiles --skill nix-tutor-kohdice

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Learning Nix is notoriously difficult: lazy evaluation, derivations, the store, flakes, and the module system all behave unlike mainstream languages, and error messages are cryptic. This Skill turns the AI into a patient Nix tutor that explains not just what code does, but why Nix works that way, so beginners eventually write Nix on their own. ## Core Features & Use Cases - Beginner-friendly explanations: Conclusion-first answers with minimal runnable code examples, step-by-step breakdowns, and explicit type annotations, always in Japanese. - Structured error diagnosis: Explains evaluation errors (infinite recursion, hash mismatches, missing attributes, pure evaluation violations) in a fixed sequence: what happened, why, where, how to fix, and how to avoid it. - Concept comparisons and mental models: Contrasts easily confused pairs (let vs rec, override vs overrideAttrs, mkIf vs plain if, strings vs paths) and teaches the Nix mental model with simplified diagrams of evaluation, derivations, and the store. - Use Case: A user hits error: infinite recursion encountered in a Home Manager module. The tutor explains that a plain if config.x creates a definition-order loop, shows the minimal fix with lib.mkIf, and explains why the module system merges definitions rather than executing them. ## Quick Start Ask the tutor to explain why your flake fails with a hash mismatch error and how to fix it using lib.fakeHash.

Frequently Asked Questions about nix-tutor

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I learn the Nix language as a beginner?▼

Start with lazy evaluation, attribute sets, and functions taking one argument, then progress to derivations and flakes. This tutor explains each concept with minimal examples runnable via nix eval or nix repl, plus the reasoning behind Nix's design.

Why does Nix say infinite recursion encountered?▼

The error means evaluating a value requires that same value, usually from rec shadowing or a module using plain if on config instead of lib.mkIf. The tutor explains the cycle, locates it with --show-trace, and shows the minimal fix.

What is the difference between let and rec in Nix?▼

let binds names to values in a simple scope, while rec lets an attribute set reference its own attributes. rec risks infinite recursion through name shadowing, so official best practices recommend let or finalAttrs in most cases.

Does the tutor support flakes and classic Nix workflows?▼

Yes. It assumes Nix 2.35.x with flakes enabled by default, but for existing projects it detects the baseline from nix --version, flake.lock pins, and whether the project uses flakes or classic default.nix and shell.nix files.

How do I fix a hash mismatch in fixed-output derivation?▼

Replace the hash with lib.fakeHash, run the build once, and copy the correct hash from the error output. The tutor explains why fetched content needs a declared hash and how fixed-output derivations enable network access in the sandbox.

When should I not use the Nix tutor skill?▼

Avoid it for implementation, refactoring, or code-review deliverables, which are explicitly out of scope. It is a teaching persona that explains concepts and minimal fixes rather than producing production code or performing reviews.