feat: external skills

flake.nix

@@ -7,13 +7,132 @@
     let
       supportedSystems = [ "x86_64-linux" "aarch64-linux" "aarch64-darwin" ];
       forAllSystems = nixpkgs.lib.genAttrs supportedSystems;
+      inherit (nixpkgs) lib;
     in {
-      # Composable runtime for project flakes and home-manager.
+
+      # ── Skill composition library ──────────────────────────────────
+      #
+      # Merges custom skills with external skills.sh sources into a
+      # single directory suitable for ~/.config/opencode/skills or
+      # .agents/skills in project flakes.
+      #
+      # Usage (home-manager):
+      #   xdg.configFile."opencode/skills".source =
+      #     inputs.agents.lib.mkOpencodeSkills {
+      #       pkgs = nixpkgs.legacyPackages.${system};
+      #       customSkills = "${inputs.agents}/skills";
+      #       externalSkills = [
+      #         { src = inputs.skills-anthropic; }
+      #         { src = inputs.skills-vercel; selectSkills = [ "find-skills" ]; }
+      #       ];
+      #     };
+      #
+      # Usage (project flake — project-level skills):
+      #   ".agents/skills".source =
+      #     inputs.agents.lib.mkOpencodeSkills {
+      #       pkgs = nixpkgs.legacyPackages.${system};
+      #       externalSkills = [
+      #         { src = inputs.skills-anthropic; selectSkills = [ "mcp-builder" ]; }
+      #       ];
+      #     };
+      #
+      # Parameters:
+      #   pkgs           — nixpkgs package set (required)
+      #   customSkills   — path to a directory of skill subdirectories (optional)
+      #   externalSkills — list of external skill sources (optional, default [])
+      #     Each element is an attrset:
+      #       src          — path to repo root (flake input or local path)
+      #       skillsDir    — subdirectory containing skills (default "skills")
+      #       selectSkills — list of skill names to include (default: all)
+      #
+      # Collision handling:
+      #   Custom skills always take priority over external ones.
+      #   Among external sources, earlier entries in the list take priority.
+
+      lib.mkOpencodeSkills =
+        { pkgs
+        , customSkills ? null
+        , externalSkills ? []
+        }:
+        let
+          # Resolve a single external source into a list of { name, path } entries.
+          resolveExternal = entry:
+            let
+              skillsRoot = "${entry.src}/${entry.skillsDir or "skills"}";
+              # List skill subdirectories (each must contain SKILL.md).
+              allSkillDirs = lib.pipe (builtins.readDir skillsRoot) [
+                (lib.filterAttrs (_: type: type == "directory"))
+                (dirs: lib.attrNames dirs)
+              ];
+              selected =
+                if entry ? selectSkills
+                then builtins.filter (name: builtins.elem name entry.selectSkills) allSkillDirs
+                else allSkillDirs;
+            in
+              map (name: { inherit name; path = "${skillsRoot}/${name}"; }) selected;
+
+          # Collect all external skills, flattened.
+          allExternal = lib.concatMap resolveExternal externalSkills;
+
+          # Collect custom skill names for collision detection.
+          customSkillNames =
+            if customSkills != null
+            then lib.attrNames (lib.filterAttrs (_: type: type == "directory") (builtins.readDir customSkills))
+            else [];
+
+          # Filter out external skills that collide with custom ones.
+          # Among externals, keep first occurrence (earlier sources win).
+          filterExternals = externals:
+            let
+              go = acc: remaining:
+                if remaining == []
+                then acc.result
+                else
+                  let
+                    head = builtins.head remaining;
+                    tail = builtins.tail remaining;
+                    isDuplicate = builtins.elem head.name acc.seen;
+                  in
+                    if isDuplicate
+                    then go acc tail
+                    else go {
+                      seen = acc.seen ++ [ head.name ];
+                      result = acc.result ++ [ head ];
+                    } tail;
+            in
+              go { seen = customSkillNames; result = []; } externals;
+
+          filteredExternal = filterExternals allExternal;
+
+          # Build a linkFarm entry for each external skill.
+          externalLinks = map (skill: {
+            name = skill.name;
+            path = skill.path;
+          }) filteredExternal;
+
+          # Build a linkFarm entry for each custom skill.
+          customLinks =
+            if customSkills != null
+            then map (name: {
+              inherit name;
+              path = "${customSkills}/${name}";
+            }) customSkillNames
+            else [];
+
+        in
+          pkgs.linkFarm "opencode-skills" (customLinks ++ externalLinks);
+
+      # ── Composable runtime ─────────────────────────────────────────
+      #
+      # Runtime dependencies for skill scripts (Python packages, system
+      # tools). Include in home.packages or project devShells.
+      #
       # Usage:
       #   home.packages = [ inputs.agents.packages.${system}.skills-runtime ];
       #   devShells.default = pkgs.mkShell {
       #     packages = [ inputs.agents.packages.${system}.skills-runtime ];
       #   };
+
       packages = forAllSystems (system:
         let
           pkgs = nixpkgs.legacyPackages.${system};
@@ -49,7 +168,8 @@
           };
         });
 
-      # Dev shell for working on this repo (wraps skills-runtime).
+      # ── Dev shell ──────────────────────────────────────────────────
+
       devShells = forAllSystems (system:
         let
           pkgs = nixpkgs.legacyPackages.${system};