Agent Skills Nix

agent-skills-nix

Manage Agent Skills (directories containing SKILL.md) declaratively with Nix. Pin skill sources, select the skills you need, and install them through Home Manager or project-local commands. You can also export selected skills as a self-contained Agent Plugin.

Nothing is installed by default: choose both skills and targets explicitly.

Quick start with Home Manager

For an existing flake-based Home Manager configuration, add these inputs to your flake:

inputs = {
  agent-skills.url = "github:Kyure-A/agent-skills-nix";
  anthropic-skills = {
    url = "github:anthropics/skills";
    flake = false;
  };
};

Capture the flake inputs with outputs = inputs@{ ... }: ...;. Add inputs.agent-skills.homeManagerModules.default to your existing Home Manager modules list and pass extraSpecialArgs = { inherit inputs; }; to home-manager.lib.homeManagerConfiguration. This makes the named skill input available to the module.

Then add the following to your Home Manager configuration:

programs.agent-skills = {
  enable = true;

  sources.anthropic = {
    input = "anthropic-skills";
    subdir = "skills";
  };

  skills.enable = [ "frontend-design" "skill-creator" ];
  targets.claude.enable = true;
};

Apply your Home Manager configuration as usual. The selected skills are synced to ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills. Enable other agents with targets.<name>.enable = true;; see default target paths. For an existing non-empty skills directory, see destination ownership.

The complete quickstart examples show both ways to arrange the inputs:

• Main flake: keep agent-skills and skill sources alongside your Home Manager inputs.
• Child flake: keep the skill inputs in a separate catalog flake.

How it works

1. Sources point to skill roots in flake inputs, local paths, or an optional source registry.
2. Discovery scans for SKILL.md files and builds a catalog. Nested skill IDs use /, such as documents/pdf; idPrefix adds a source namespace.
3. Selection chooses catalog entries with skills.enable or skills.enableAll, and custom declarations with skills.explicit.
4. Bundling builds the selection in the Nix store, including any content transforms and package dependencies.
5. Targets install the bundle for enabled agents. Explicit skills can limit installation to named targets with agents.

Guides and examples

Task	Guide	Example
Configure sources, select skills, and customise content	Configuration	Transforms and dependencies
Install skills in a project	Installation	Local install flake
Install automatically on shell entry	Development shells	devShell flake
Pin sources without a flake input per repository	Source registry	Registry flake
Export a portable skills-only plugin	Agent Plugin export (experimental)	Plugin flake
Build your own integration	Library and flake reference	Library snippet

The root flake has an empty catalog and no enabled targets. Installation commands such as nix run .#skills-install-local must run against your own configured flake. Home Manager installs skills when you activate your home configuration; it does not add apps to your flake.

Default target paths

Use agents to install a shared skill set for tools that discover .agents/skills. Claude Code uses its own skill directory:

Target	Global path	Local path
agents (shared)	$HOME/.agents/skills	.agents/skills
claude	${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills	.claude/skills

Product-specific targets remain available for separate installation destinations and features that require a dedicated path. See the full target list.

All built-in targets are disabled by default. Global targets use symlink-tree; local targets use copy-tree. See target configuration for custom paths, structures, and system filters.

Development

The root flake.nix depends only on nixpkgs. It wires the library, packages, apps, checks, and Home Manager module through ordinary Nix imports:

Directory	Contents
lib/	Discovery, selection, bundling, targets, registry, and plugin export
modules/	Shared options and Home Manager integration
nix/	Package, app, and default configuration definitions
scripts/	Synchronization, source locking, and plugin validation runtimes
test/	Library and runtime checks, plus Home Manager integration tests
examples/	Consumer configurations

Home Manager is a test-only dependency in test/flake.nix, which imports the root flake through a relative path and follows its nixpkgs input. Consumers do not inherit a Home Manager dependency.

Run both check suites from the repository root:

nix flake check
nix flake check ./test

To update dependencies, update the root lock first, then the test lock:

nix flake update
nix flake update --flake ./test

CI runs both suites and checks formatting with nix fmt. The dependency update workflow updates both lock files.