agent-skills-nix

Declarative management of Agent Skills (directories containing SKILL.md) with flake-pinned sources, discovery, selection, bundling, Home Manager integration, and skills-only Agent Plugin export.

Concepts

• sources: Named inputs or paths pointing at a skills root (subdir). They can be written directly as before, or generated from the optional source registry. Optional idPrefix namespaces discovered skill IDs to avoid collisions across sources.
• discover: Recursively scans sources for directories that contain SKILL.md, producing a catalog. Skills can be nested (e.g. ecosystem/c-ecosystem/) and their IDs use / as separator.
• skills.enable / skills.enableAll / skills.explicit: Declaratively pick discovered skills, enable-all (global or by source list), and explicitly specified ones. Explicit skills can restrict installation to named targets with agents; no accidental auto-install unless you opt in.
• Agent Plugin export: Maps selected catalog entries to portable skill names and produces a self-contained, skills-only plugin directory.
• targets: Agent-specific destinations synced from a store bundle (structure: link, symlink-tree, copy-tree). Targets are opt-in (enable = false by default). Runtime destinations support $HOME, ~, and ${VAR:-$HOME/...} fallback forms without general shell evaluation. See Default target paths below.

Source filters

Each source supports optional filters to control discovery:

• idPrefix (null | string, default: null): Prefix prepended to discovered skill IDs. Useful when multiple sources expose the same relative path, e.g. idPrefix = "openai"; turns pdf into openai/pdf.
• filter.maxDepth (null | int, default: null): Maximum recursion depth for SKILL.md discovery. null = unlimited (capped internally at 100 to guard against symlink loops), 0 = source root only, 1 = immediate children, 2 = one level of nesting. Negative depths are rejected.
• filter.nameRegex (null | string, default: null): Regex matched against the skill's relative path (e.g. cat-a/skill-1) to restrict discovery.

If two sources both expose pdf, prefix them explicitly to keep IDs unique:

sources.openai = {
  input = "openai-skills";
  subdir = "skills";
  idPrefix = "openai";
};

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

skills.enable = [ "openai/pdf" "anthropic/pdf" ];

Direct sources, Home Manager sources, and registry manifests use the same validation for subdir, idPrefix, and filter. Unknown source/filter fields, invalid types, unsafe relative paths, and invalid ID prefixes fail before selection. A source must provide path or input; path takes precedence when both are set.

Source registry (optional)

The source registry removes the need to declare every skill repository as a flake input. It uses npins, the pin manager recommended by the nix.dev remote-source guide, for revision resolution and hashing. Existing sources.<name>.input and sources.<name>.path declarations remain supported and can be mixed with this approach.

Keep one human-edited Nix manifest per source and commit the generated JSON lock:

registry/
├── sources/
│   ├── anthropic.nix
│   └── internal.nix
└── sources.lock.json