# Agent Skill

The [Nixomatic Agent Skill](https://github.com/curriedsoftware/nixomatic-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](https://code.claude.com/) and [Codex](https://openai.com/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

```bash
# 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

```bash
# 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:

1. **Project analysis** — Scans dependency files (`package.json`, `Cargo.toml`, `go.mod`, etc.) to identify required packages
2. **Environment construction** — Generates a nixomatic URL with the detected packages
3. **Command execution** — Runs commands inside a `nix develop` environment
4. **Error recovery** — If a command fails due to a missing tool, it adds the package and retries
5. **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/nix` image

## 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 | `nodejs@20.11.1` | Specific version (resolved via [nxv](https://nxv.urandom.io/)) |
| Pinned | `python3:3b93cf5` | Exact nixpkgs commit for full reproducibility |

For more details, see the [Nixomatic Agent Skill on GitHub](https://github.com/curriedsoftware/nixomatic-skill).