nix-workflow
Skill9 starsChanged 55 days agoMITView on GitHub
Choose Nix commands, locate store paths and libraries, use development shells, debug builds, configure Nix and navigate ecosystem tools.
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- devenv-projectSkill
- home-managerSkill
- microvm-nixSkill
- nix-darwinSkill
- nix-languageSkill
- nixos-coding-agentsSkill
- nixos-operationsSkill
- nixos-wikiSkill
- nixpkgs-developmentSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 9
Check nix --version, since Nix, Lix and Determinate Nix differ.
- Distinctive: line 27
Do not install into the user's profile or system to satisfy one project.
- Distinctive: line 28
Search before inventing: When a build or package fails:
- Very specific: line 29
Read the full log with nix log.
- Distinctive: line 30
Search NixOS/nixpkgs issues and pull requests for the distinctive error text.
- Distinctive: line 34
Do not disable the sandbox, checks or hardening to make an error disappear.
- Very specific: line 52
Never search /nix/store (for example find /nix/store/*foo-* -name libfoo.so) and never copy a literal store path.
- Very specific: line 56
Do not quote attribute names that are valid identifiers ([A-Za-z_][A-Za-z0-9_'-]*, dashes included).
≈ “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.
Files
Nix workflow
Establish the context before advising. Read the repository's own instructions.
Check nix --version, since Nix, Lix and Determinate Nix differ. Check whether
nix-command and flakes are enabled (nix config show experimental-features),
and whether the project pins inputs with a flake, npins, niv or channels.
Advice that fits one of these can be wrong for another.
Rules
- Never search
/nix/storeby brute force. Afindorlsover the store only sees what happens to be built locally. It misses everything else, and a path copied from it breaks as soon as the store changes. Usenix-locateto find which package provides a file. Use store queries (nix path-info,nix why-depends) for dependencies. Refer to libraries through Nix expressions such as${pkgs.openssl.out}/liborlib.makeLibraryPath, never through literal store paths. - Use the right environment.
- For a project, use its
devShellsoutput withnix develop. - For a tool the user needs for a moment, use
nix shell nixpkgs#tool. - For one program, use
nix run. - Do not install into the user's profile or system to satisfy one project.
- For a project, use its
Search before inventing. When a build or package fails:
- Read the full log with
nix log. - Search NixOS/nixpkgs issues and pull requests for the distinctive error text.
- Report what you found, with numbers, before proposing a workaround.
Do not disable the sandbox, checks or hardening to make an error disappear.
- Read the full log with
- Use the smallest adequate tool. Inspect and transform data with
jq,awk,sed,grepandnixsubcommands such asnix eval --jsonandnix derivation show. Write Python or another script only when the logic needs it. - Know where a setting lives. Nix settings belong to the client, the
daemon or a remote builder. Some take effect only for trusted users. On
NixOS, nix-darwin and Home Manager, Nix configuration is declarative, and
generated files are not edited by hand. Do not edit
nix.conf, add trusted users or substituters, collect garbage, or switch a system without the user's explicit authorization. Propose the change instead. - Treat ecosystem facts as perishable. Tools and lang2nix projects are archived, renamed or replaced often. Before recommending one, check its upstream repository for its status and any successor. Prefer the Nixpkgs language builders first.
Nix style
- Never search
/nix/store(for examplefind /nix/store/*foo-* -name libfoo.so) and never copy a literal store path. Find the providing package withnix-locate, and refer to it through Nix:${pkgs.foo}/liborlib.makeLibraryPath [ pkgs.foo ]. - Do not quote attribute names that are valid identifiers
(
[A-Za-z_][A-Za-z0-9_'-]*, dashes included). Writepkgs.foo-barandpackages.x86_64-linux, notpkgs."foo-bar". Quote only other names (".config/foo","2.0"), the keywordsassert else if in inherit let or rec then with, and interpolations ("${name}"). Upstream examples in references sometimes quote needlessly; do not copy that style.
References
- Finding things: which package provides a file, store and dependency queries, and referring to libraries from Nix.
- Shells:
nix develop,nix shell,nix run, defining devShells, direnv, and project versus host tools. - Troubleshooting: evaluation versus build errors, reading logs, and searching Nixpkgs issues, pull requests and Hydra.
- Configuration: settings precedence, the client and daemon, trusted users, caches, remote builders and declarative owners.
- Ecosystem: helper tools, pinning, flake frameworks, Nix implementations and lang2nix status.
Other skills by role
These skills belong to the same collection, but may not all be installed. If one is missing, use the linked upstream documentation instead.
| Role | Typical need | Use |
| Developer | Project environment, expressions | This skill for shells; devenv-project for devenv (devenv.sh); nix-language for the language (Nix manual) |
| Packager | Derivations, overrides, overlays | nixpkgs-development (Nixpkgs manual) |
| Home Manager user, including darwin | User configuration | home-manager (Home Manager manual) |
| macOS system administrator | nix-darwin system configuration | nix-darwin (nix-darwin) |
| NixOS administrator | System configuration and rebuilds | nixos-operations for rebuilds, generations, upgrades, store cleaning, boot and services; nixos-wiki for community guidance (NixOS manual, NixOS Wiki) |
| AI coding agent user | Choosing, installing and sandboxing coding agents | nixos-coding-agents (llm-agents.nix, agent-images, agent-box) |
| VM user | Declarative microVMs | microvm-nix (microvm.nix) |
Report what you actually ran, which commands only evaluated and which built or changed anything, and which advice you could not verify on the user's version.
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
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.

