What is nix-profile-manager?

The Nix Profile Manager skill empowers Claude agents to autonomously manage local Nix profiles, enabling the dynamic installation of tools and dependencies without requiring system-wide administrative privileges. By leveraging Nix flakes and profiles, it provides a robust framework for creating reproducible, isolated development environments, ensuring agents always have the right tools for any task while maintaining system integrity.

When should I use nix-profile-manager?

nix-profile-manager is useful in the following scenarios: • Automated Tool Provisioning: Enabling agents to search for and install necessary CLI utilities like jq, git, or specific compilers on-the-fly to complete complex technical tasks. • Isolated Environment Setup: Creating and maintaining local development environments that are independent of the host system, preventing version conflicts and ensuring reproducibility. • Dependency Resolution for Code Execution: Automatically managing software dependencies and libraries required for running or testing code within an agent's workspace. • Nix Registry and Flake Management: Providing expert guidance on configuring custom registries and using flakes to pin specific versions of software for consistent behavior.

name	nix-profile-manager
description	Expert guidance for agents to manage local Nix profiles for installing tools and dependencies. Covers flakes, profile management, package searching, and registry configuration.

Nix Profile Manager for Agents

Overview

This skill enables agents to maintain a local Nix profile in a user-provided directory, allowing dynamic installation of tools without requiring system-wide package management or sudo access.

Quick Start: Setting Up a Local Profile

Users should provide a directory in their PATH for the agent to manage, and ensure the AGENT_PROFILE env var contains this directory so the agent knows where it is.

Then the agent just does:

nix profile add --profile "$AGENT_PROFILE" "nixpkgs#git"

The --profile flag tells Nix to store the profile metadata in that location. The bin dir created by Nix in the profile must be in the PATH.

NOTE: on older Nix versions, the add sub-command was called install. Keep this in mind if you get errors saying that "add" does not exist.

Core Concepts

Profiles

A profile is a directory containing:

manifest.json - list of installed packages and their flake references
bin, lib, share, etc. - folders with symlinks to binaries, libs, docs in the Nix store

When you run nix profile add, Nix updates the manifest and recreates symlinks.

Flakes

A flake is a standardized Nix package collection with:

A flake.nix file defining inputs and outputs
Deterministic versioning via flake.lock
Multiple output schemes (packages, overlays, modules, etc.)

Common flakes:

nixpkgs - Standard package library (the default registry), usually an alias for github:NixOS/nixpkgs/nixpkgs-unstable
Custom flakes from GitHub (e.g., github:user/repo)

Packages vs. Flakes

Package: A single tool (e.g., git, python311)
Flake: A collection of packages, accessed as <flake>#<package>

IMPORTANT: In some flakes (like nixpkgs) packages can be nested: <flake>#<scope>.<package>

Essential Commands

Search for Packages

# Search in nixpkgs flake:
nix search nixpkgs git

# Search in specific (fully qualified) flake
nix search "github:user/repo[/branch]" <package-name>

# Or get a more detailed JSON output
nix search nixpkgs python3 --json | jq '.[].pname'

Manage Profile

# Add package
nix profile add --profile <profile_path> "<flake>#<package>"

# List installed packages
nix profile list --profile <profile_path>

# Remove by index or element number
nix profile remove --profile <path>/profile 0

# Upgrade packages
nix profile upgrade --profile <profile_path> <package_name>
nix profile upgrade --profile <profile_path> --all  # All packages installed in this profile

Registry Management

# List available flake aliases
nix registry list

# Add custom registry entry (user-level)
nix registry add myflake github:user/repo/branch

General Workflow

# Determine profile path:
echo $AGENT_PROFILE  # If not defined, ask the user which profile to use!!

# Search for the package
nix search nixpkgs git

# Add it
nix profile add --profile "$AGENT_PROFILE" "nixpkgs#git"

# Just use it!
tool-cmd ...

Important Details

Profile path bin sub-folder should be in PATH: The directory containing the profile must be in $PATH for linked binaries to be accessible
Flake references are immutable: nixpkgs#git resolves to the current nixpkgs version; use github:user/repo/ref#package to pin to specific refs
Profile locking: Only one agent should modify a profile at a time; locking is not automatic
Store links don't expire: Nix store paths remain valid even if the flake changes; profiles maintain old package paths if needed

Troubleshooting

Package not found:

Ensure flake name is correct: nix registry list shows available aliases
Search with nix search <flake> <partial-name> to find exact package name

Command not in PATH after install:

Check profile directory is in $PATH: echo $PATH
Verify $AGENT_PROFILE was created: ls -la $AGENT_PROFILE (adjust path as needed)

Permission denied:

Local profiles DO NOT require sudo. Report to user in case of permission problems

References

references/flakes.md - In-depth flake concepts and GitHub references
references/package-search.md - Advanced package discovery techniques
references/profile-internals.md - Profile structure and manifest format
references/registry.md - Custom registry configuration and pinning

For Agent Implementation

When implementing profile management in an agent:

Accept profile path as environment variable or parameter - e.g., AGENT_PROFILE or function arg
Always search before installing - verify package exists and name is exact
Use --json output for parsing - more reliable than text output
Handle errors gracefully - packages may not exist in all flakes
Notify about profile modifications - help users track what was installed

nix-profile-manager

When & Why to Use This Skill

Use Cases