Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Hand-written and generated references

Each skill has two kinds of content.

Hand-written

Every SKILL.md is written and reviewed by hand: when to use the skill, rules, routing, and the Nix style rules. Two skills are hand-written throughout, nix-workflow and nixos-coding-agents; they link to upstream documentation instead of copying it, because their sources change too often to copy.

Hand-written text changes only through reviewed pull requests, and automated updates never replace it.

Generated from upstream

The other skills also carry references/ generated from upstream sources: the Nix manual, the NixOS manual, Nixpkgs documentation, the Home Manager and nix-darwin repositories, microvm.nix, devenv, and a retained NixOS Wiki dump.

Each such skill has a sources.json that records:

  • the upstream repository or dump, and the branch, release or snapshot;
  • the exact revision or snapshot hash the text was generated from;
  • which upstream files were selected, with their hashes;
  • the hash of every generated output file.

scripts/check.py recomputes these hashes offline, so any hand edit to a generated file, or any mismatch with its recorded source, fails the check. The skill catalog shows each skill’s upstream and pin.

Licences

Generated text is a copy of upstream material and keeps its upstream licence, which ships with the skill as LICENSE or COPYING: for example LGPL-2.1 for the Nix manual, MIT for Nixpkgs, NixOS and Home Manager text, and Apache-2.0 for devenv. The repository does not relicense copied material. Hand-written skills are covered by the repository licence.

Per-skill sources and licences

Each package records its upstream snapshot identity, curated selection, and input/output hashes in its own sources.json. References cover selected topics, not every upstream feature. Agents must check the project’s actual versions. The Nix skill does not supply NixOS options or replace Nixpkgs API documentation. The portable devenv-project skill is distinct from a machine-specific devenv policy skill and upstream’s devenv-setup; their behavior is not interchangeable. Each skill can be installed independently.

Home Manager references originate in nix-community/home-manager and retain its accompanying LICENSE. microvm.nix references originate in microvm-nix/microvm.nix and retain its accompanying LICENSE. nix-darwin references originate in nix-darwin/nix-darwin and retain its accompanying LICENSE. These packages record the selected branch revision, source-file hashes, and generated-output hashes in sources.json; the repository does not relicense copied upstream material.

Design history: intent, spec, implementation plan.

The copied references originate in Nix, whose upstream README identifies LGPL v2.1; the upstream licence accompanies the skill as COPYING. Generated references identify the Nix contributors and link to original files at the recorded revision. The repository does not relicense that material under MIT or another permissive licence. The manifest tracks source files, generator helpers, the full language dump, and generated hashes for reproduction.

Design history: intent, spec, implementation plan.

Devenv references originate in cachix/devenv, under its accompanying Apache-2.0 LICENSE. The manifest hashes selected narrative pages, committed generated data, generators/templates, the upstream setup skill, and the documentation coverage. Modified excerpts retain source attribution. The repository does not relicense Nix material under devenv’s license.

Devenv design history: intent, spec, implementation plan.

Nixpkgs references originate in NixOS/nixpkgs, under its accompanying MIT COPYING. The license of the nixdoc generator does not replace the upstream source license. Nixpkgs design history: intent, spec, implementation plan.

Wiki text is from the official NixOS Wiki, under the retained MIT COPYING from copyright-policy revision 22887. Media can have other terms and is excluded. Wiki design history: intent, spec, plan.