skills.nix

A Nix-packaged collection of agent skills following the Agent Skills standard

---

🌄 Overview

skills.nix is a curated catalog of agent skills packaged with Nix flakes, providing one-command installation of skills for AI coding agents. Think of it as an “awesome-list” of agent skills with reproducible Nix integration.

Every skill follows the Agent Skills standard, making them compatible with Pi, Claude Code, Gemini CLI, and other agents that support the standard.

✨ Skills

team-play — Distinguished / staff+ role prompts for engineering, review, security, UX, and orchestration

• Compatibility: Any agent that supports SKILL.md
• Invoke: /skill:team-play (in Pi)

A small library of role prompts that shape an agent into a distinguished-level specialist for a specific task. Each prompt establishes identity, non-negotiable standards, evaluation criteria, verification steps, and output format.

Shipped roles (use as starting points, adapt to your project’s conventions):

• engineer/ — go, rust, svelte, zig
• reviewer/ — go, rust, svelte, zig
• security/ — code-audit, infra, supply-chain
• ux-designer/ — cli, mobile, tablet, tui, web-frontend
• orchestrator/ — manager

Extending team-play

Use lib.mkTeamPlay to merge in your own role directories — add new roles in new categories, add languages / platforms to existing categories, or override the shipped files entirely. The base SKILL.md is preserved.

{ inputs, pkgs, ... }:
let
  skills-nix = inputs.skills-nix;
  system = pkgs.stdenv.hostPlatform.system;
in
{
  imports = [ skills-nix.homeModules.default ];

  programs.agent-skills = {
    enable = true;
    skills = [
      # Built-in team-play with your extra roles merged in
      (skills-nix.lib.mkTeamPlay {
        inherit pkgs;
        extraRoles = [
          # Each entry is a directory laid out like:
          #   <dir>/<category>/<role>.md
          # e.g. my-roles/engineer/python.md, my-roles/dba/postgres.md
          ./my-roles
          inputs.company-roles      # works with any flake input or path
        ];
      })
    ];
    pi.enable = true;
  };
}

Merge semantics:

• Files at the same path override the base (your file wins).
• New categories / files are added alongside the built-in ones.
• The top-level SKILL.md cannot be removed; the build fails loudly if an extraRoles entry overwrites it.

mkTeamPlay returns a regular skill derivation — use it anywhere you’d use a packaged skill (in skills, in mkRemoteSkills, etc.).

user-context suite — my-env / my-tools / my-style / my-workflow (templates to fill in per machine)

Agents repeatedly suggest commands and write prose that don’t match your machine — apt-get install on NixOS, brew on Linux, force-pushing when you never force-push, verbose preambles when you want terse lists. The fix is to give the agent a small, sharp reference that it loads only when relevant.

This suite is that reference: four focused skills, each with a tight description that triggers only on the right kind of task, so the agent gets the right context at the right moment without flooding every turn with everything you’ve ever told it.

The templates ship empty by design — they are not drop-in skills. Install one only after you’ve filled it in with your own content. An untouched template’s frontmatter explicitly tells agents the file is unfilled, so installing one verbatim correctly refuses to give the agent any user-specific context.

The four are designed as a suite with non-overlapping trigger keywords so implicit invocation picks the right one for a given task.

my-env — OS / shell / WM / hardware / secret store

• Trigger: shell, OS, distro, WM, hardware, pass, credentials
• Body sections: Machine · Window manager · Shell / direnv · Terminal · Secret storage

Load before suggesting commands that depend on the host OS, shell, terminal, or that need to retrieve credentials from the user’s secret store.

my-tools — install / build / editor / formatter / LSP / paths

• Trigger: install, add, fetch, build, editor, formatter, LSP, repos
• Body sections: Package managers · Banned tools · One-off invocation · Build/test · Editor/LSP · Stable paths

Load before suggesting install, add, fetch, build commands, or invoking an editor / formatter / LSP. Describes which tools are allowed, which are banned, and where things live.

my-style — commit / PR / docs / response prose

• Trigger: commit message, PR description, documentation, response prose
• Body sections: Commit messages · PR descriptions · Documentation · Agent response style

Load when writing any text intended for the user or for a repository’s history.

my-workflow — git / PR mechanics / merge / rebase / deploy

• Trigger: git, PR, merge, deploy, review, rebase, force-push
• Body sections: Branching · PR opening / review · Merging / rebasing / force-push · Releases / deploys

Load before any version-control action, opening or reviewing a PR, or running a deploy. Covers how a change is handled (my-style covers what its text says).

Customizing the templates

The four templates are intended to be customized per machine, not installed verbatim. Recommended workflow:

1. Seed the templates you care about into your dotfiles repo. The shipped my-context CLI handles the bookkeeping for you:

   # All four → ~/dotfiles/skills
   nix run github:rytswd/skills.nix#my-context -- -o ~/dotfiles/skills
   
   # Or just a subset
   nix run github:rytswd/skills.nix#my-context -- -o ~/dotfiles/skills my-env my-tools
   
   # See `--help` for --force, etc.
   nix run github:rytswd/skills.nix#my-context -- --help
       

   The CLI skips files that already exist (use --force to overwrite) and prints a ready-to-paste localSkills block at the end so you can copy it straight into your home-manager config.

2. Edit each file (delete sections you don’t care about; an empty section wastes context tokens).
3. Mount only the ones you actually filled in via localSkills:

   programs.agent-skills.localSkills = {
     my-env      = "${config.home.homeDirectory}/dotfiles/skills/my-env.md";
     my-tools    = "${config.home.homeDirectory}/dotfiles/skills/my-tools.md";
     # Skip the ones you haven't filled in — absent entries don't
     # burn description tokens or risk misleading the agent.
   };
       

Edits to the .md files take effect immediately (out-of-store symlinks); no home-manager switch needed unless you add or remove entries.

If you’d rather have your customised content built and pinned by Nix, use skills with a small wrapper derivation that copies your file into $out/share/agent-skills/<name>/SKILL.md. The localSkills path is recommended for most users because preferences tend to change faster than dotfiles get rebuilt.

kagi-search — Web search & summarization via Kagi APIs

• Compatibility: Requires KAGI_API_KEY, curl, jq
• Invoke: /skill:kagi-search (in Pi)
• Scripts: scripts/search.sh, scripts/summarize.sh

Search the web and summarize content using Kagi’s APIs:

• search.sh "query" [limit] — Search and format results
• summarize.sh <url-or-text> [engine] [type] — Summarize any content

Summarizer supports articles, PDFs, YouTube, audio, PowerPoint, Word docs. Three engines: cecil (fast), agnes (formal), muriel (best quality). Two output types: summary (prose) or takeaway (bullet points).

workmux-workflow — Orchestration patterns for parallel AI agents using workmux

• Compatibility: Requires workmux, git, and tmux
• Invoke: /skill:workmux-workflow (in Pi)

Patterns for the orchestrator role when coordinating multiple AI agents:

• Task decomposition with non-overlapping file scopes
• Prompt template with file scope, context references, and commit instructions
• Spawn → monitor → review → merge workflow
• Anti-patterns: overlapping scopes, missing commit before merge, too many parallel agents

workmux — 5 upstream skills from raine/workmux (vendored via lib.mkRemoteSkills)

• Source: raine/workmux upstream (pinned to v0.1.118)
• Compatibility: Requires workmux, git, and tmux
• Update: nix flake lock --override-input workmux-src github:raine/workmux/v<NEW>

Installs all 5 workmux skills directly from upstream:

Skill	Description	Invoke
worktree	Dispatch tasks to new git worktrees	/skill:worktree
coordinator	Orchestrate multiple worktree agents	/skill:coordinator
merge	Commit, rebase, and merge the current branch	/skill:merge
open-pr	Write PR description and open in browser	/skill:open-pr
rebase	Smart rebase with conflict resolution	/skill:rebase

context7 — Library documentation lookup via Context7

• Compatibility: Requires curl and jq; optionally npx for MCP setup
• Invoke: /skill:context7 (in Pi)
• Scripts: scripts/query.sh

Look up current, version-specific library documentation:

• query.sh resolve "nextjs" — Find a library’s Context7 ID
• query.sh docs "/vercel/next.js" "app router" — Query documentation
• Also documents MCP server setup for native integration

📦 Installation

Prerequisites

• Nix with flakes enabled
• Home Manager (for the recommended installation method)

Home Manager (Recommended)

Import the home-manager module and declare which skills you want for which agents:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
    home-manager.url = "github:nix-community/home-manager";
    skills-nix.url = "github:rytswd/skills.nix";
  };
}

# In your home-manager configuration:
{ inputs, pkgs, ... }:
{
  imports = [ inputs.skills-nix.homeModules.default ];

  programs.agent-skills = {
    enable = true;
    skills = with inputs.skills-nix.packages.${pkgs.stdenv.hostPlatform.system}; [
      kagi-search
      context7
      workmux
    ];
    pi.enable = true;       # → ~/.agents/skills/
    claude.enable = true;   # → ~/.claude/skills/
    gemini.enable = true;   # → ~/.agents/skills/
  };
}

Skills are listed once in skills; agent targets are boolean flags. The module handles agent-specific layout differences automatically.

See Adding Skills for how to add remote, local, or new skills beyond what’s included.

Try Locally

Build and inspect individual skills without installing:

nix build github:rytswd/skills.nix#kagi-search
find -L result/ -type f

nix build github:rytswd/skills.nix#context7
cat result/share/agent-skills/context7/SKILL.md

🔌 Agent Configuration

The home-manager module places skills in the correct discovery directory for each agent:

Agent	enable flag	Directory	Discovery
Pi	pi.enable = true	~/.agents/skills/	Cross-agent convention, recursive
Codex	codex.enable = true	~/.agents/skills/	Cross-agent convention, recursive
Claude Code	claude.enable = true	~/.claude/skills/	Flat <name>/SKILL.md only
Gemini CLI	gemini.enable = true	~/.agents/skills/	Cross-agent convention, recursive

Skills are declared once — the module handles agent-specific layout differences automatically.

Remote skill layout

Remote skill sources (e.g., workmux) bundle multiple skills under a single directory. Since Claude Code doesn’t support recursive SKILL.md discovery, the module flattens them with a __ separator:

Agent	Layout	Example
Pi, Codex, Gemini	Nested	workmux/coordinator/SKILL.md
Claude	Flattened	workmux__coordinator/SKILL.md

This applies to any remote skill integration — grouping by origin is automatic.

➕ Adding Skills

Three ways to add skills to your setup: remote git sources, local filesystem paths, or contributing directly to this repo. All skills follow the Agent Skills standard — a directory containing SKILL.md with YAML frontmatter (name and description), plus optional scripts/, references/, and assets/ subdirectories.

Remote skills — pull from any git repo with lib.mkRemoteSkills

Use lib.mkRemoteSkills to pull skills from any git repo — no changes to skills.nix needed:

# flake.nix
{
  inputs = {
    skills-nix.url = "github:rytswd/skills.nix";
    # Add any repo containing SKILL.md files:
    cool-skills-src = {
      url = "github:someone/cool-skills";
      flake = false;
    };
  };
}

# In your home-manager configuration:
{ inputs, pkgs, ... }:
let
  skills-nix = inputs.skills-nix;
  system = pkgs.stdenv.hostPlatform.system;
in
{
  imports = [ skills-nix.homeModules.default ];

  programs.agent-skills = {
    enable = true;
    skills = [
      # Built-in skills
      skills-nix.packages.${system}.kagi-search

      # Any remote repo with SKILL.md files
      (skills-nix.lib.mkRemoteSkills {
        inherit pkgs;
        name = "cool-skills";       # Groups under cool-skills/<skill>/
        src = inputs.cool-skills-src;
        skillsDir = "skills";        # Subdirectory containing skills (optional)
      })
    ];
    pi.enable = true;
  };
}

mkRemoteSkills scans the source for SKILL.md files and packages them under <name>/<skill>/. Works with any git repo, tarball, or fetchurl source.

Local skills — symlink unpublished or private skills via localSkills

For private or unpublished skills that live on your local filesystem, use localSkills. These are symlinked directly (not copied into the Nix store), so changes take effect immediately without rebuilding:

{ inputs, pkgs, ... }:
{
  imports = [ inputs.skills-nix.homeModules.default ];

  programs.agent-skills = {
    enable = true;
    skills = with inputs.skills-nix.packages.${pkgs.stdenv.hostPlatform.system}; [
      kagi-search
      context7
    ];

    # Local skills: name → absolute path to directory containing SKILL.md
    localSkills = {
      air-workflow = /home/user/my-skills/air-workflow;
      my-private-skill = /home/user/my-skills/private;
    };

    pi.enable = true;
  };
}

Each entry creates a symlink from the agent’s skill directory (e.g., ~/.agents/skills/air-workflow) directly to the local path. The value can also point at a single .md file (it is mounted as <name>/SKILL.md with the containing directory created automatically). This is ideal for:

• Skills based on unpublished tools
• Personal workflow skills you don’t want to share
• Skills under active development
• Customising the user-context suite (my-env, my-tools, my-style, my-workflow) — see that section for the recommended seed-and-edit workflow.

In this repo — contribute a new skill to the catalog

To contribute a new skill to the catalog:

1. Create skills/my-skill/SKILL.md following the Agent Skills standard:

---
name: my-skill
description: What this skill does and when to use it.
---

# My Skill

Instructions for the agent...

1. Create nix/packages/my-skill/default.nix:

{ pkgs, ... }:

pkgs.runCommand "my-skill" { } ''
  mkdir -p $out/share/agent-skills/my-skill
  cp -r ${../../skills/my-skill}/* $out/share/agent-skills/my-skill/
''

1. Build and test:

nix build .#my-skill
find -L result/ -type f

🧪 Development

# Build a specific skill
nix build .#kagi-search

# Check flake
nix flake check

# Show available packages
nix flake show

📄 License

MIT