agent-skills-nix

The examples/ directory provides several use-case-oriented patterns for implementing agent-skills-nix in your projects:

• Quickstart patterns: Demonstrates two ways to structure skills: a main pattern where skills are tightly coupled, and a child pattern where skills are organized into a separated catalog.
• Library functions: Shows how to use the project's internal library helpers directly.
• Agent Plugin export: Demonstrates how to export a selection of skills as a self-contained, skills-only Agent Plugin (experimental).
• Skill customization: Provides examples of using transform and packages to customize skill behavior.
• Local installation: Shows how to create a project-local install app using mkLocalInstallProgram.
• Development shell: Demonstrates auto-installing dependencies within a development shell using mkShellHook.
• Source registry: Explains how to use per-source manifests combined with an npins JSON lock to manage skills without requiring a separate flake input for every skill repository.

agent-skills-nix provides declarative management of Agent Skills (directories containing a SKILL.md file). Key abstractions include:

• sources: Named inputs or paths pointing to a skills root (subdir). You can use idPrefix to namespace discovered skill IDs to prevent collisions.
• discover: A process that recursively scans sources for SKILL.md files to produce a catalog. Nested skills use / as a separator (e.g., ecosystem/c-ecosystem/).
• Selection: Skills are picked using skills.enable (specific list), skills.enableAll (global or by source), or skills.explicit (restricts installation to named targets).
• Agent Plugin export: A mechanism to map catalog entries to portable names and produce a self-contained, skills-only plugin directory.
• targets: Agent-specific destinations (e.g., claude, copilot, cursor) where skills are synced. Targets are opt-in and use different sync structures (link, symlink-tree, or copy-tree).

You can use the agents option on an explicit skill to control which named targets receive it. This is useful for deploying different skill sets to different AI agents (e.g., Claude vs. Codex).

• agents = [ "agent-name" ];: Only that agent receives the skill.
• agents = null; or omitted: The skill is sent to every enabled target on the system.
• agents = [];: The skill is included in the full bundle but installed nowhere.

Note: If any selected skill has a non-null agents list, you cannot use AGENT_SKILLS_DESTS or AGENT_SKILLS_LOCAL_DESTS environment variables to override destinations, as those variables do not identify a specific target.

programs.agent-skills = {
  targets.claude.enable = true;
  targets.codex.enable = true;
  targets.pi.enable = true;

  skills.explicit = {
    writing = {
      from = "my-source";
      agents = [ "claude" "codex" ];
    };
    pi-tools = {
      from = "my-source";
      agents = [ "pi" ];
    };
    shared = {
      from = "my-source";
    };
  };
};

The source registry allows you to manage skill repositories without declaring every one as a flake input. It uses npins for revision resolution and hashing.

1. Create Manifests: Maintain human-edited Nix manifests in a registry/sources/ directory.
2. Define Pins: Use pin.type (github, git, or tarball). For GitHub, specify owner, repo, and branch.
3. Generate Lock: Use the skills-sources-lock app to resolve pins and generate registry/sources.lock.json.
4. Load in Nix: Use agentLib.sourcesFromLock to load the registry.

Example manifest (registry/sources/anthropic.nix):

{
  pin = {
    type = "github";
    owner = "anthropics";
    repo = "skills";
    branch = "main";
  };

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

Example loading in your configuration:

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

catalog = agentLib.discoverCatalog sources;

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

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