Getting started

This tutorial installs the skills for one agent on NixOS, checks that the agent sees them, and gives you the first prompt to use. It assumes Home Manager is used as a NixOS module in a flake-based system configuration. For other setups, see Install the skills.

1. Add the input and enable the module

Add the input to your system flake, and commit the lock file:

inputs.nix-skills.url = "github:olafkfreund/nix-skills";

Enable the module for your user (replace alice; inputs must be in scope), and pick your agents:

home-manager.users.alice = {
  imports = [ inputs.nix-skills.homeManagerModules.default ];
  programs.nix-skills = {
    enable = true;
    agents = [ "claude" ];
  };
};

Rebuild through NixOS with nixos-rebuild, never home-manager switch. The agents values are listed in Install the skills.

2. Check that the agent sees them

ls ~/.claude/skills   # or your agent's directory

Then, in the agent, run /skills (Claude Code, Codex) or ask “Which skills do you have available?” (OpenCode, Antigravity). If a skill is missing, see Fix skill discovery.

3. Start with this prompt

Open your agent in your system configuration repository and paste:

Use the nix-skills skills. I'm on NixOS and want to set up this machine for
agentic coding. Read my system configuration first, tell me what you found,
and propose changes as a diff. Do not rebuild, install or run containers
until I approve.

4. Try more requests

The full list is in the skill catalog.

Next: agentic coding on NixOS

As a NixOS user with no AI agent yet, I want a coding agent set up declaratively, and optionally sandboxed, so that I can start agentic coding without breaking my system or exposing my secrets.

1. Run an agent once, without installing it.

   nix run github:numtide/llm-agents.nix#claude-code   # or #codex, #opencode, #antigravity-cli
   

   Check: it starts, and nothing is installed.

2. Install the skills for that agent, as in step 1 above, and rebuild. Check: as in step 2 above.

3. Give the start prompt from your system configuration repository. Check: the agent reads your configuration and proposes a diff without applying it. Typically the diff adds the llm-agents.nix input and your agent, the Numtide binary cache, and optionally virtualisation.podman.enable for sandboxing.

4. Review the diff, then build and switch yourself: nixos-rebuild build, then nixos-rebuild switch. Check: the agent is on your PATH without nix run. Undo: roll back to the previous generation.

5. Per project. In a code repository, ask for a devenv shell (devenv-project). For repositories you do not trust, ask to run the agent in a container or an agent-box worktree (nixos-coding-agents). Check: the devenv shell activates, and the sandbox check from nixos-coding-agents stories 3 and 4 passes.

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.

The demo VM and Set up your own machine now cover steps 1 to 4 in a single command or import.