agents.nix

# agents.nix

Nix expressions for AI agent skills, plugins, marketplaces, and Kiro powers.

Each package is sourced from a GitHub repository, pinned to a specific revision, and available through a nixpkgs overlay.

## Prerequisites

### (Optional) Enable flakes

Read about [Nix flakes](https://wiki.nixos.org/wiki/Flakes) and [set them up](https://wiki.nixos.org/wiki/Flakes#Setup).

## Overlay

Read about [Overlays](https://wiki.nixos.org/wiki/Overlays#Using_overlays).

### With flakes

Add `agents.nix` to your flake inputs:

```nix
{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
    agents-nix.url = "github:sudosubin/agents.nix";
  };

  outputs = { nixpkgs, agents-nix, ... }:
    let
      pkgs = import nixpkgs {
        system = "aarch64-darwin"; # or "x86_64-linux", etc.
        overlays = [ agents-nix.overlays.default ];
      };
    in
    {
      # pkgs.agent-skills.github.<owner>.<repo>.<skill-name>
    };
}
```

### Without flakes

```nix
let
  agents-nix = import (builtins.fetchGit {
    url = "https://github.com/sudosubin/agents.nix";
    ref = "refs/heads/main";
  });

  pkgs = import <nixpkgs> {
    overlays = [ agents-nix.overlays.default ];
  };
in
  # pkgs.agent-skills.github.<owner>.<repo>.<skill-name>
```

## Usage

### Get `agent-plugins`

Agent Plugins are available under `pkgs.agent-plugins`:

```nix
pkgs.agent-plugins.github.<owner>.<repo>.<plugin-name>
```

### Get `agent-skills`

#### Get `agent-skills` via the overlay

After applying the overlay (see [Overlay](#overlay)), skills are available under `pkgs.agent-skills`:

```nix
pkgs.agent-skills.github.<owner>.<repo>.<skill-name>
```

#### Get `agent-skills` from `agents.nix` directly

Without the overlay, you can access skills from the flake outputs:

```nix
agents-nix.agent-skills.${system}.github.<owner>.<repo>.<skill-name>
```

### Get `claude-code-marketplaces`

Claude Code marketplaces are available under `pkgs.claude-code-marketplaces`:

```nix
pkgs.claude-code-marketplaces.github.<owner>.<repo>.<marketplace-name>
```

### Get `claude-code-plugins`

Claude Code plugins are available under `pkgs.claude-code-plugins`:

```nix
pkgs.claude-code-plugins.github.<owner>.<repo>.<plugin-name>
```

### Get `codex-marketplaces`

Codex marketplaces are available under `pkgs.codex-marketplaces`:

```nix
pkgs.codex-marketplaces.github.<owner>.<repo>.<marketplace-name>
```

This namespace collects `.agents/plugins/marketplace.json`, or
`.agents/plugins/api_marketplace.json` when the first file is absent. Claude Code
and Cursor catalogs belong to their own namespaces. Compatible marketplace
packages can still be combined by the consuming application.

### Get `codex-plugins`

Codex plugins are available under `pkgs.codex-plugins`:

```nix
pkgs.codex-plugins.github.<owner>.<repo>.<plugin-name>
```

### Get `copilot-marketplaces`

Copilot marketplaces are available under `pkgs.copilot-marketplaces`:

```nix
pkgs.copilot-marketplaces.github.<owner>.<repo>.<marketplace-name>
```

### Get `copilot-plugins`

Copilot plugins are available under `pkgs.copilot-plugins`:

```nix
pkgs.copilot-plugins.github.<owner>.<repo>.<plugin-name>
```

### Get `kiro-powers`

Kiro powers with `POWER.md` are available under `pkgs.kiro-powers`.
Use `pkgs.agent-plugins` for powers in the Agent Plugins format.

```nix
pkgs.kiro-powers.github.<owner>.<repo>.<power-name>
```

### Skill identifiers

Skills are organized in a four-level hierarchy: `github.<owner>.<repo>.<skill-name>`.

- `github` — the forge the repository lives on
- `owner` — repository owner, lower-cased (e.g., `vercel-labs`)
- `repo` — repository name, lower-cased (e.g., `skills`)
- `skill-name` — skill directory name (e.g., `find-skills`)

For example, a skill from the repository `vercel-labs/skills` would be accessed as:

```nix
pkgs.agent-skills.github.vercel-labs.skills.find-skills
```

> [!NOTE]
> If a skill identifier contains characters that aren't valid Nix identifiers, quote them like `pkgs.agent-skills.github."01000001-01001110"."agent-jira-skills"."jira-issues"`.

> [!IMPORTANT]
> `pkgs.skills.<owner>.<repo>.<skill-name>` still resolves and warns on evaluation. It is kept for existing configurations only.

### Example: install a skill for claude-code

```nix
# home-manager configuration
{ pkgs, ... }:

{
  programs.claude-code = {
    enable = true;
    skills = {
      find-skills = pkgs.agent-skills.github.vercel-labs.skills.find-skills;
    };
  };
}
```

### Example: install a skill for pi

```nix
# home-manager configuration
{ pkgs, ... }:

{
  home.file.".pi/agent/skills/find-skills" = {
    source = pkgs.agent-skills.github.vercel-labs.skills.find-skills;
    recursive = true;
  };
}
```

### Rename a skill

By default, `SKILL.md` is preserved unchanged. The derivation `pname` comes from the lowercased skill directory name, or the repository name for skills at the repository root.

Use `.override { name = "..."; }` to change both the derivation `pname` and the `

... (truncated)