Nix Shell Skill

1. Purpose

Use this skill to search for Nix packages and run commands using tools that are not installed locally. It wraps nix search, nix-locate, and nix shell to give the agent on-demand access to any package in nixpkgs.

2. Usage Scenarios

Run when:

• A command or tool is needed but not installed locally.
• You need to find which Nix package provides a specific binary.
• You need to run a one-off command with a tool from nixpkgs.
• You need multiple tools available together for a pipeline.

3. Helper Scripts

4. Subcommands

search <term> [--json] [--timeout DURATION]

Search nixpkgs for packages matching <term>.

• Default output: Clean table with package name, version, and description.
• --json: Raw JSON output from nix search.
• --timeout DURATION: Override the search timeout (default: 5m). Format follows GNU coreutils (e.g. 30s, 5m, 1h).
• If no packages match, prints a message and exits 0.

locate <pattern> [-t TYPE] [-n LIMIT] [--timeout SECS] [-w]

Find which Nix package provides a specific file or binary. Uses nix-locate with --minimal output.

• Default type: x (executable). Other types: r (regular file), d (directory), s (symlink).
• Default limit: 100 results (use -n to change).
• Default timeout: 60 seconds (use --timeout to change).
• -w / --whole-name: Only match files whose basename matches the pattern exactly.
• Output is one attribute name per line (e.g. coreutils-prefixed.out).

run <packages...> -- <command> [args...]

Run a command with specified Nix packages available on PATH.

• Packages: Bare names are auto-prefixed with nixpkgs# (e.g. envsubst becomes nixpkgs#envsubst). Full flake references (containing # or :) pass through unchanged.
• -- separator is required between packages and the command.
• The process is replaced via exec, so the exit code comes directly from the executed command.

5. Examples

Search for a package

scripts/nix_shell.sh search envsubst

Search with JSON output

scripts/nix_shell.sh search envsubst --json

Locate which package provides a binary

scripts/nix_shell.sh locate gtimeout

Locate with exact basename match and limited results

scripts/nix_shell.sh locate gtimeout -w -n 10

Locate regular files instead of executables

scripts/nix_shell.sh locate nginx.conf -t r

Run a command with a single package

scripts/nix_shell.sh run envsubst -- envsubst --help

Run with multiple packages

scripts/nix_shell.sh run envsubst jq -- sh -c 'echo "{}" | jq . && which envsubst'

Use a full flake reference

scripts/nix_shell.sh run github:NixOS/nixpkgs#hello -- hello

6. Output Format

Search (default table)

envsubst            1.4.3     Substitute environment variables in a string

Search (--json)

{
  "legacyPackages.aarch64-darwin.envsubst": {
    "pname": "envsubst",
    "version": "1.4.3",
    "description": "Substitute environment variables in a string"
  }
}

Locate

One attribute name per line (minimal output):

coreutils-prefixed.out

Run

Outputs whatever the executed command produces (stdout and stderr pass through).

7. Exit Codes

8. Environment Variables

9. Troubleshooting