agentleFS
olafkfreundolafkfreund/nix-skills/skills/nixpkgs-development/SKILL.md

nixpkgs-development

Skill9 starsChanged 55 days agoMITView on GitHub

Write, explain, review, and debug Nixpkgs package expressions, build helpers, overrides, overlays, and library APIs against the project's pinned package set.

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 6 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read the repository instructions, existing package expressions, and actual Nixpkgs input/lock before editing.

    line 8
  2. Distinctive:

    Read only the relevant reference:

    line 15
  3. Distinctive:

    Prefer an existing appropriate build helper.

    line 43
  4. Distinctive:

    Do not disable checks, sandboxing, or hardening to hide an unexplained failure.

    line 48
  5. Distinctive:

    Start validation with the target package set and bounded checks for the change.

    line 50
  6. Very specific:

    Before working around a build or packaging failure, read the full build log, then search NixOS/nixpkgs issues and pull requests for the …

    line 56
  7. Distinctive:

    Use nixpkgs-review to build what a Nixpkgs change affects:

    line 63
  8. Very specific:

    Never search /nix/store (for example find /nix/store/*foo-* -name libfoo.so) and never copy a literal store path.

    line 88
  9. Very specific:

    Do not quote attribute names that are valid identifiers ([A-Za-z_][A-Za-z0-9_'-]*, dashes included).

    line 92

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Nixpkgs development

Read the repository instructions, existing package expressions, and actual Nixpkgs input/lock before editing. Keep its package layout, overlays, and development environment conventions. Distinguish the Nix evaluator version, Nixpkgs revision, and build/host/target platforms. The bundled references describe the master snapshot in sources.json; they are not a stable-release claim or proof that an API exists in an older consumer pin.

Read only the relevant reference:

  • Packaging: stdenv, dependency roles, phases/hooks, metadata, and package tests.
  • Customization: argument overrides, attribute overrides, overlays, and generic module composition.
  • Helpers: fetchers/hashes, small builders, mkShell, and entry points for Python, JavaScript, Go, and Rust packaging.
  • Library: selected generated API descriptions, types, arguments, and examples with pinned declarations.
  • Contributing: Nixpkgs' own contributor rules. These cover pull requests and review, target branches and mass rebuilds, commit messages, pkgs/by-name placement, package naming, versioning, patches and automatic updates. Read it for any change intended for Nixpkgs itself.

For library and NixOS module contributions, also read upstream's lib/README.md and nixos/README.md. These links follow the master branch; they are not pinned.

Choose the mechanism that matches the change: override changes recipe arguments; overrideAttrs changes mkDerivation inputs; overlays compose package sets; module options merge configuration. In overlays, use the previous package for its original recipe and the final set for dependencies; inspect self-reference when diagnosing recursion. Inspect the target recipe before assuming every language helper has the same override behavior.

Prefer an existing appropriate build helper. Preserve pre/post hooks when replacing phases, keep native build tools distinct from host dependencies, and inspect platform assumptions. A temporary fake hash is a discovery aid: finish with the verified hash for the selected fetcher/source. Preserve upstream lockfiles and update consumer inputs deliberately, not merely to match these references. Do not disable checks, sandboxing, or hardening to hide an unexplained failure.

Start validation with the target package set and bounded checks for the change. Report evaluation, actual builds, and runtime tests separately. Documentation examples can use historical versions or illustrative values; inspect them before adapting or running them. Do not execute arbitrary snippets merely to read docs. Respect existing task authorization and keep secrets out of the Nix store.

Before working around a build or packaging failure, read the full build log, then search NixOS/nixpkgs issues and pull requests for the distinctive error and the package name, for example gh search issues --repo NixOS/nixpkgs "<error>" and gh search prs --repo NixOS/nixpkgs "<package>". Cite what you found, and whether a fix has reached the user's pin, before proposing a local workaround.

Use nixpkgs-review to build what a Nixpkgs change affects:

  • nixpkgs-review wip for uncommitted changes;
  • nixpkgs-review rev HEAD for a commit;
  • nixpkgs-review pr NUMBER for a pull request.

It builds every affected package, which can be many and slow, so check the scope and ask before running it on a large change. Read its report of failed, broken and skipped packages before stating a result. Never use post-result, approve, merge, --post-result or --approve-pr without the user's explicit authorization: they act on GitHub under the user's identity.

Version-bump pull requests from r-ryantm come from nixpkgs-update. Review them like any update: read the upstream changelog, build with nixpkgs-review pr, and check the linked update logs.

This skill does not supply a complete package/API catalogue or NixOS/Home Manager option reference. Host installation and deployment follow local policy. Public manual links can move; packaged excerpts and source citations are revision-pinned. Modified upstream material is covered by COPYING.

Nix style

  • Never search /nix/store (for example find /nix/store/*foo-* -name libfoo.so) and never copy a literal store path. Find the providing package with nix-locate, and refer to it through Nix: ${pkgs.foo}/lib or lib.makeLibraryPath [ pkgs.foo ].
  • Do not quote attribute names that are valid identifiers ([A-Za-z_][A-Za-z0-9_'-]*, dashes included). Write pkgs.foo-bar and packages.x86_64-linux, not pkgs."foo-bar". Quote only other names (".config/foo", "2.0"), the keywords assert else if in inherit let or rec then with, and interpolations ("${name}"). Upstream examples in references sometimes quote needlessly; do not copy that style.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.