From 029c4a77065f32db35eb3d19c505fb4db729ce62 Mon Sep 17 00:00:00 2001
From: Chris Denneen <cdenneen@gmail.com>
Date: Mon, 23 Mar 2026 12:53:15 -0400
Subject: [PATCH] Add reusable flake modules and CI eval coverage

Signed-off-by: Chris Denneen <cdenneen@gmail.com>
---
 .github/workflows/nix-flake.yaml | 164 ++++++++++++++
 README.md                        |  70 ++++++
 flake.lock                       |  27 +++
 flake.nix                        | 368 +++++++++++++++++++++++++++++++
 4 files changed, 629 insertions(+)
 create mode 100644 .github/workflows/nix-flake.yaml
 create mode 100644 flake.lock
 create mode 100644 flake.nix

diff --git a/.github/workflows/nix-flake.yaml b/.github/workflows/nix-flake.yaml
new file mode 100644
index 0000000..76ac8f9
--- /dev/null
+++ b/.github/workflows/nix-flake.yaml
@@ -0,0 +1,164 @@
+name: nix-flake
+
+on:
+  pull_request:
+    paths:
+      - "flake.nix"
+      - "flake.lock"
+      - "README.md"
+      - "skills/**"
+      - "agents/**"
+      - ".github/workflows/nix-flake.yaml"
+  push:
+    branches:
+      - main
+    paths:
+      - "flake.nix"
+      - "flake.lock"
+      - "README.md"
+      - "skills/**"
+      - "agents/**"
+      - ".github/workflows/nix-flake.yaml"
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@v21
+
+
+      - name: Evaluate flake outputs
+        run: |
+          set -euo pipefail
+
+          nix flake show --all-systems
+          nix eval .#lib.skillNames
+          nix eval .#lib.agentProfileNames
+          nix eval .#lib.supportedTools
+
+          test "$(nix eval --raw --apply 'x: if builtins.isFunction x then "true" else "false"' .#homeManagerModules.default)" = "true"
+          test "$(nix eval --raw --apply 'x: if builtins.isFunction x then "true" else "false"' .#nixosModules.default)" = "true"
+          test "$(nix eval --raw --apply 'x: if builtins.isFunction x then "true" else "false"' .#darwinModules.default)" = "true"
+
+      - name: Smoke test installer
+        run: |
+          set -euo pipefail
+
+          expected="$(find skills -mindepth 1 -maxdepth 1 -type d | wc -l | tr -d ' ')"
+          tmp="$(mktemp -d)"
+
+          nix run .#install -- --target "$tmp/.agents/skills"
+          actual_agents="$(find "$tmp/.agents/skills" -mindepth 1 -maxdepth 1 \( -type l -o -type d \) | wc -l | tr -d ' ')"
+
+          nix run .#install -- --tool codex --target "$tmp/.codex/skills"
+          actual_codex="$(find "$tmp/.codex/skills" -mindepth 1 -maxdepth 1 \( -type l -o -type d \) | wc -l | tr -d ' ')"
+
+          test "$actual_agents" = "$expected"
+          test "$actual_codex" = "$expected"
+
+          test -f "$tmp/.agents/skills/gitops-knowledge/SKILL.md"
+          test -f "$tmp/.agents/skills/gitops-repo-audit/SKILL.md"
+          test -f "$tmp/.agents/skills/gitops-cluster-debug/SKILL.md"
+
+      - name: Consumer flake evals (HM + NixOS + nix-darwin)
+        run: |
+          set -euo pipefail
+
+          repo_path="$PWD"
+          tmp_root="$(mktemp -d)"
+
+          hm_dir="$tmp_root/hm"
+          mkdir -p "$hm_dir"
+          cat > "$hm_dir/flake.nix" <<HM
+          {
+            inputs = {
+              nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
+              home-manager.url = "github:nix-community/home-manager/release-25.11";
+              home-manager.inputs.nixpkgs.follows = "nixpkgs";
+              fluxcd-agent-skills.url = "path:${repo_path}";
+            };
+
+            outputs = { nixpkgs, home-manager, fluxcd-agent-skills, ... }: {
+              homeConfigurations.test = home-manager.lib.homeManagerConfiguration {
+                pkgs = import nixpkgs { system = "x86_64-linux"; };
+                modules = [
+                  fluxcd-agent-skills.homeManagerModules.default
+                  {
+                    home.username = "test";
+                    home.homeDirectory = "/tmp/test-home";
+                    home.stateVersion = "25.11";
+                    programs."fluxcd-agent-skills".enable = true;
+                    programs."fluxcd-agent-skills".tools = [ "codex" ];
+                  }
+                ];
+              };
+            };
+          }
+          HM
+
+          nix eval "$hm_dir#homeConfigurations.test.activationPackage.drvPath"
+
+          nixos_dir="$tmp_root/nixos"
+          mkdir -p "$nixos_dir"
+          cat > "$nixos_dir/flake.nix" <<NIXOS
+          {
+            inputs = {
+              nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
+              fluxcd-agent-skills.url = "path:${repo_path}";
+            };
+
+            outputs = { nixpkgs, fluxcd-agent-skills, ... }: {
+              nixosConfigurations.test = nixpkgs.lib.nixosSystem {
+                system = "x86_64-linux";
+                modules = [
+                  fluxcd-agent-skills.nixosModules.default
+                  {
+                    system.stateVersion = "25.11";
+                    boot.loader.grub.devices = [ "nodev" ];
+                    fileSystems."/" = {
+                      device = "/dev/disk/by-label/nixos";
+                      fsType = "ext4";
+                    };
+                    programs."fluxcd-agent-skills".enable = true;
+                    programs."fluxcd-agent-skills".targets = [ "/tmp/agent-skills" ];
+                  }
+                ];
+              };
+            };
+          }
+          NIXOS
+
+          test "$(nix eval --json "$nixos_dir#nixosConfigurations.test.config.programs.\"fluxcd-agent-skills\".enable")" = "true"
+
+          darwin_dir="$tmp_root/darwin"
+          mkdir -p "$darwin_dir"
+          cat > "$darwin_dir/flake.nix" <<DARWIN
+          {
+            inputs = {
+              nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
+              nix-darwin.url = "github:LnL7/nix-darwin";
+              nix-darwin.inputs.nixpkgs.follows = "nixpkgs";
+              fluxcd-agent-skills.url = "path:${repo_path}";
+            };
+
+            outputs = { nix-darwin, fluxcd-agent-skills, ... }: {
+              darwinConfigurations.test = nix-darwin.lib.darwinSystem {
+                system = "aarch64-darwin";
+                modules = [
+                  fluxcd-agent-skills.darwinModules.default
+                  {
+                    system.stateVersion = 6;
+                    programs."fluxcd-agent-skills".enable = true;
+                    programs."fluxcd-agent-skills".targets = [ "/Users/test/.agents/skills" ];
+                  }
+                ];
+              };
+            };
+          }
+          DARWIN
+
+          test "$(nix eval --json "$darwin_dir#darwinConfigurations.test.config.programs.\"fluxcd-agent-skills\".enable")" = "true"
diff --git a/README.md b/README.md
index 6e11f70..8cbe097 100644
--- a/README.md
+++ b/README.md
@@ -49,6 +49,76 @@ For Claude Code, add the marketplace and install the skills with:
 /plugin install gitops-skills@fluxcd
 ```
 
+### Using Nix Flake
+
+This repository includes a minimal Nix flake for consumers who want a generic,
+tool-agnostic skills install flow.
+
+Install skills into the default location (`.agents/skills`):
+
+```shell
+nix run github:fluxcd/agent-skills#install
+```
+
+Install for a specific tool path:
+
+```shell
+nix run github:fluxcd/agent-skills#install -- --tool codex
+nix run github:fluxcd/agent-skills#install -- --tool claude-code
+nix run github:fluxcd/agent-skills#install -- --tool gemini
+nix run github:fluxcd/agent-skills#install -- --tool kiro
+```
+
+Install to an explicit directory:
+
+```shell
+nix run github:fluxcd/agent-skills#install -- --target .my-agent/skills
+```
+
+The flake discovers skill directories dynamically from `skills/` at evaluation time,
+so newly added skills are included automatically without hardcoding names.
+
+### As a Flake Input
+
+The flake exposes reusable modules for Home Manager, NixOS, and nix-darwin:
+
+- `homeManagerModules.default`
+- `nixosModules.default`
+- `darwinModules.default`
+
+Home Manager example:
+
+```nix
+{
+  inputs.fluxcd-agent-skills.url = "github:fluxcd/agent-skills";
+
+  outputs = { self, nixpkgs, home-manager, fluxcd-agent-skills, ... }: {
+    homeConfigurations.me = home-manager.lib.homeManagerConfiguration {
+      pkgs = import nixpkgs { system = "x86_64-linux"; };
+      modules = [
+        fluxcd-agent-skills.homeManagerModules.default
+        {
+          programs."fluxcd-agent-skills".enable = true;
+          programs."fluxcd-agent-skills".tools = [ "codex" ];
+        }
+      ];
+    };
+  };
+}
+```
+
+NixOS / nix-darwin (without Home Manager) example:
+
+```nix
+{
+  imports = [ fluxcd-agent-skills.nixosModules.default ]; # or darwinModules.default
+  programs."fluxcd-agent-skills".enable = true;
+  programs."fluxcd-agent-skills".targets = [ "/home/alice/.agents/skills" ];
+}
+```
+
+In system modules, `targets` must be absolute paths and the links are created during activation.
+
 ## Prerequisites
 
 The skills in this repository rely on the following tools being available in the environment:
diff --git a/flake.lock b/flake.lock
new file mode 100644
index 0000000..b1da6fd
--- /dev/null
+++ b/flake.lock
@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1774244481,
+        "narHash": "sha256-4XfMXU0DjN83o6HWZoKG9PegCvKvIhNUnRUI19vzTcQ=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "4590696c8693fea477850fe379a01544293ca4e2",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-25.11",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}
diff --git a/flake.nix b/flake.nix
new file mode 100644
index 0000000..eda430c
--- /dev/null
+++ b/flake.nix
@@ -0,0 +1,368 @@
+{
+  description = "Nix flake packaging for FluxCD agent skills";
+
+  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
+
+  outputs =
+    {
+      self,
+      nixpkgs,
+    }:
+    let
+      lib = nixpkgs.lib;
+
+      systems = [
+        "x86_64-linux"
+        "aarch64-linux"
+        "x86_64-darwin"
+        "aarch64-darwin"
+      ];
+
+      forAllSystems =
+        f:
+        lib.genAttrs systems (
+          system:
+          f system (
+            import nixpkgs {
+              inherit system;
+            }
+          )
+        );
+
+      readSubdirs =
+        dir:
+        let
+          entries = builtins.readDir dir;
+        in
+        builtins.filter (name: entries.${name} == "directory") (builtins.attrNames entries);
+
+      skillNames =
+        builtins.filter
+          (name: builtins.pathExists (./skills + "/${name}/SKILL.md"))
+          (readSubdirs ./skills);
+
+      agentProfileNames = readSubdirs ./agents;
+
+      toolTargets = {
+        codex = ".codex/skills";
+        claude = ".claude/skills";
+        claude-code = ".claude/skills";
+        gemini = ".gemini/skills";
+        gemini-cli = ".gemini/skills";
+        gemeni = ".gemini/skills";
+        kiro = ".kiro/skills";
+        kiro-cli = ".kiro/skills";
+      };
+
+      supportedTools = lib.sort builtins.lessThan (builtins.attrNames toolTargets);
+
+      toolTarget = tool: toolTargets.${tool};
+
+      mkSkillEntries =
+        target:
+        map (name: {
+          name = "${target}/${name}";
+          value = {
+            source = ./skills + "/${name}";
+            recursive = true;
+          };
+        }) skillNames;
+
+      mkHomeModule =
+        {
+          config,
+          lib,
+          pkgs,
+          ...
+        }:
+        let
+          cfg = config.programs."fluxcd-agent-skills";
+          effectiveTargets = lib.unique (cfg.targets ++ map toolTarget cfg.tools);
+
+          links = builtins.listToAttrs (lib.concatMap mkSkillEntries effectiveTargets);
+        in
+        {
+          options.programs."fluxcd-agent-skills" = {
+            enable = lib.mkEnableOption "FluxCD agent skills";
+
+            package = lib.mkOption {
+              type = lib.types.package;
+              default = self.packages.${pkgs.system}.skills;
+              description = "Package containing all FluxCD skill directories.";
+            };
+
+            installPackage = lib.mkOption {
+              type = lib.types.package;
+              default = self.packages.${pkgs.system}.install;
+              description = "Installer helper package (fluxcd-agent-skills-install).";
+            };
+
+            targets = lib.mkOption {
+              type = lib.types.listOf lib.types.str;
+              default = [ ".agents/skills" ];
+              example = [ ".agents/skills" ".tools/skills" ];
+              description = "Home-relative or absolute directories where skills are linked.";
+            };
+
+            tools = lib.mkOption {
+              type = lib.types.listOf (lib.types.enum supportedTools);
+              default = [ ];
+              example = [ "codex" "claude-code" ];
+              description = "Convenience aliases that add tool-specific target directories.";
+            };
+          };
+
+          config = lib.mkIf cfg.enable {
+            home.file = links;
+            home.packages = [ cfg.installPackage ];
+          };
+        };
+
+      mkSystemModule =
+        {
+          config,
+          lib,
+          pkgs,
+          ...
+        }:
+        let
+          cfg = config.programs."fluxcd-agent-skills";
+          targets = cfg.targets;
+          targetArgs = map lib.escapeShellArg targets;
+        in
+        {
+          options.programs."fluxcd-agent-skills" = {
+            enable = lib.mkEnableOption "FluxCD agent skills";
+
+            package = lib.mkOption {
+              type = lib.types.package;
+              default = self.packages.${pkgs.system}.skills;
+              description = "Package containing all FluxCD skill directories.";
+            };
+
+            installPackage = lib.mkOption {
+              type = lib.types.package;
+              default = self.packages.${pkgs.system}.install;
+              description = "Installer helper package (fluxcd-agent-skills-install).";
+            };
+
+            targets = lib.mkOption {
+              type = lib.types.listOf lib.types.str;
+              default = [ ];
+              example = [ "/home/alice/.agents/skills" "/Users/alice/.codex/skills" ];
+              description = "Absolute directories where skills are linked during activation.";
+            };
+          };
+
+          config = lib.mkIf cfg.enable {
+            assertions = map (target: {
+              assertion = lib.hasPrefix "/" target;
+              message = "programs.fluxcd-agent-skills.targets entries must be absolute paths: ${target}";
+            }) targets;
+
+            environment.systemPackages = [ cfg.installPackage ];
+
+            system.activationScripts.fluxcdAgentSkills = lib.mkIf (targets != [ ]) {
+              text = ''
+                set -eu
+
+                skills_root=${lib.escapeShellArg cfg.package}
+
+                for target in ${lib.concatStringsSep " " targetArgs}; do
+                  mkdir -p "$target"
+
+                  for skill_src in "$skills_root"/*; do
+                    [ -d "$skill_src" ] || continue
+
+                    name="$(basename "$skill_src")"
+                    dst="$target/$name"
+
+                    if [ -L "$dst" ] || [ -e "$dst" ]; then
+                      rm -rf "$dst"
+                    fi
+
+                    ln -s "$skill_src" "$dst"
+                  done
+                done
+              '';
+            };
+          };
+        };
+    in
+    {
+      lib = {
+        inherit
+          skillNames
+          agentProfileNames
+          supportedTools
+          ;
+      };
+
+      homeManagerModules.default = mkHomeModule;
+      nixosModules.default = mkSystemModule;
+      darwinModules.default = mkSystemModule;
+
+      packages = forAllSystems (
+        system: pkgs:
+        let
+          skills = pkgs.linkFarm "fluxcd-agent-skills" (
+            map (name: {
+              name = name;
+              path = ./skills + "/${name}";
+            }) skillNames
+          );
+
+          agentProfiles = pkgs.linkFarm "fluxcd-agent-profiles" (
+            map (name: {
+              name = name;
+              path = ./agents + "/${name}";
+            }) agentProfileNames
+          );
+
+          install = pkgs.writeShellApplication {
+            name = "fluxcd-agent-skills-install";
+            runtimeInputs = [ pkgs.coreutils ];
+            text = ''
+              set -euo pipefail
+
+              usage() {
+                cat <<'HELP'
+              Usage: fluxcd-agent-skills-install [--tool <name>] [--target <path>] [--copy] [--force]
+
+              Options:
+                --tool <name>    Use a standard target path for a tool.
+                                 Supported: codex, claude-code, gemini, kiro
+                --target <path>  Explicit target directory (overrides --tool mapping)
+                --copy           Copy skill directories instead of symlinking
+                --force          Replace non-symlink existing skill directories
+                --list           Print discovered skills and exit
+                --help           Show this help
+
+              Defaults:
+                target: .agents/skills
+                mode:   symlink
+              HELP
+              }
+
+              mode="symlink"
+              force=0
+              tool=""
+              target=""
+
+              skills_root='${skills}'
+
+              while [[ $# -gt 0 ]]; do
+                case "$1" in
+                  --tool)
+                    tool="''${2:-}"
+                    shift 2
+                    ;;
+                  --target)
+                    target="''${2:-}"
+                    shift 2
+                    ;;
+                  --copy)
+                    mode="copy"
+                    shift
+                    ;;
+                  --force)
+                    force=1
+                    shift
+                    ;;
+                  --list)
+                    find "$skills_root" -mindepth 1 -maxdepth 1 -type d -exec basename {} \; | sort
+                    exit 0
+                    ;;
+                  --help|-h)
+                    usage
+                    exit 0
+                    ;;
+                  *)
+                    echo "Unknown option: $1" >&2
+                    usage
+                    exit 2
+                    ;;
+                esac
+              done
+
+              if [[ -z "$target" ]]; then
+                case "$tool" in
+                  "")
+                    target=".agents/skills"
+                    ;;
+                  codex)
+                    target=".codex/skills"
+                    ;;
+                  claude|claude-code)
+                    target=".claude/skills"
+                    ;;
+                  gemini|gemini-cli|gemeni)
+                    target=".gemini/skills"
+                    ;;
+                  kiro|kiro-cli)
+                    target=".kiro/skills"
+                    ;;
+                  *)
+                    echo "Unsupported --tool value: $tool" >&2
+                    echo "Supported values: codex, claude-code, gemini, kiro" >&2
+                    exit 2
+                    ;;
+                esac
+              fi
+
+              mkdir -p "$target"
+
+              installed=0
+              for skill_src in "$skills_root"/*; do
+                [[ -d "$skill_src" ]] || continue
+
+                name="$(basename "$skill_src")"
+                dst="$target/$name"
+
+                if [[ -e "$dst" || -L "$dst" ]]; then
+                  if [[ -L "$dst" ]]; then
+                    rm -f "$dst"
+                  elif [[ "$force" -eq 1 ]]; then
+                    rm -rf "$dst"
+                  else
+                    echo "Skipping $name: $dst exists (use --force to replace)" >&2
+                    continue
+                  fi
+                fi
+
+                if [[ "$mode" == "copy" ]]; then
+                  cp -a "$skill_src" "$dst"
+                else
+                  ln -s "$skill_src" "$dst"
+                fi
+
+                installed=$((installed + 1))
+              done
+
+              echo "Installed $installed skill(s) to $target"
+            '';
+          };
+        in
+        {
+          default = skills;
+          inherit
+            install
+            skills
+            ;
+          agent-profiles = agentProfiles;
+        }
+      );
+
+      apps = forAllSystems (system: pkgs: {
+        default = {
+          type = "app";
+          program = "${pkgs.lib.getExe self.packages.${system}.install}";
+        };
+
+        install = {
+          type = "app";
+          program = "${pkgs.lib.getExe self.packages.${system}.install}";
+        };
+      });
+    };
+}