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

For a GitHub source that follows a branch:

# registry/sources/anthropic.nix
{
  pin = {
    type = "github";
    owner = "anthropics";
    repo = "skills";
    branch = "main";
  };

  subdir = "skills";
  idPrefix = "anthropic";
  filter.maxDepth = 2;
}

pin.type can be github, git, or tarball. Git and GitHub pins accept branch, at, submodules, preReleases, versionUpperBound, and releasePrefix; generic Git pins additionally require url and accept forge. If branch is omitted, npins follows releases and writes a GitRelease pin. Tarball pins require url and optionally accept mutable. The remaining fields (subdir, idPrefix, and filter) are the same source discovery settings as the existing DSL.

Load the lock as an ordinary path-backed sources value:

sources = agentLib.sourcesFromLock {
  manifestsDir = ./registry/sources;
  lockFile = ./registry/sources.lock.json;
};

catalog = agentLib.discoverCatalog sources;

Expose the updater in a consumer flake:

sourceLockProgram = agentLib.mkSourceLockProgram { inherit pkgs; };

apps.${system}.skills-sources-lock = {
  type = "app";
  program = "${sourceLockProgram}/bin/skills-sources-lock";
};

Then update all sources together:

nix run .#skills-sources-lock

The command validates and normalizes every manifest through the same Nix loader used by consumers, passes every npins argument without shell evaluation, and resolves all pins in a temporary sibling directory. The generated lock has an agent-skills schema-v1 wrapper containing the normalized manifests and an npins version-8 lock. sourcesFromLock requires the current normalized manifests to match that snapshot exactly, so changing a repository, branch, or discovery option without updating the lock fails evaluation. The updater sorts JSON keys and only then atomically renames the completed lock into place. A failed manifest or fetch leaves the old lock byte-for-byte unchanged; rerunning with unchanged upstream revisions produces the same lock bytes. See the complete examples/source-registry flake.

Default target paths

Target	Global path	Local path
agents	$HOME/.agents/skills	.agents/skills
codex	${CODEX_HOME:-$HOME/.codex}/skills	.codex/skills
opencode	$HOME/.config/opencode/skills	.opencode/skills
claude	${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills	.claude/skills
copilot