Agent Skill
The Nixomatic Agent Skill enables AI coding agents to automatically set up reproducible development environments powered by Nix. It works with agents supporting the skills convention, such as Claude Code and Codex. It helps you:
- Automatically detect required packages from project dependency files
- Execute commands within a fully configured Nix environment
- Retry with missing packages when runtime errors occur
- Document the working environment configuration in your project README
Quick Start
Per-Project Setup
# For Claude Code
mkdir -p .claude/skills
ln -s /path/to/nixomatic-skill/nixomatic .claude/skills/nixomatic
# For Codex
mkdir -p .codex/skills
ln -s /path/to/nixomatic-skill/nixomatic .codex/skills/nixomatic
Global Setup
# For Claude Code (available across all projects)
ln -s /path/to/nixomatic-skill/nixomatic ~/.claude/skills/nixomatic
# For Codex (available across all projects)
ln -s /path/to/nixomatic-skill/nixomatic ~/.codex/skills/nixomatic
How It Works
Once installed, the skill activates when you ask the agent to build, test, run, or set up a project. It follows this workflow:
- Project analysis — Scans dependency files (
package.json,Cargo.toml,go.mod, etc.) to identify required packages - Environment construction — Generates a nixomatic URL with the detected packages
- Command execution — Runs commands inside a
nix developenvironment - Error recovery — If a command fails due to a missing tool, it adds the package and retries
- Documentation — Updates the project README with the finalized nixomatic URL
Detected Languages and Tools
The skill automatically maps project files to Nix packages:
| File | Package(s) |
|---|---|
package.json | nodejs |
Cargo.toml | rustc, cargo |
go.mod | go |
requirements.txt, pyproject.toml | python3 |
Gemfile | ruby |
pom.xml, build.gradle | jdk |
mix.exs | elixir |
composer.json | php |
.csproj, .fsproj | dotnet-sdk |
Package.swift | swift |
stack.yaml, .cabal | ghc, cabal-install |
pubspec.yaml | dart |
build.zig, zig.zon | zig |
Build tools are also detected:
| File | Package |
|---|---|
Makefile | gnumake |
CMakeLists.txt | cmake |
meson.build | meson |
Justfile | just |
Taskfile.yml | go-task |
Requirements
The skill requires one of the following runtimes on the system:
- Nix (with flakes support) — used natively
- Docker — falls back to the
nixos/niximage
Package Formats
The skill constructs nixomatic URLs using the same package formats available everywhere in Nix O'matic:
| Format | Example | Description |
|---|---|---|
| Basic | nodejs | Latest version from nixos-unstable |
| Versioned | [email protected] | Specific version (resolved via nxv) |
| Pinned | python3:3b93cf5 | Exact nixpkgs commit for full reproducibility |
For more details, see the Nixomatic Agent Skill on GitHub.