readyblockedneeds helpallepicskb

Design and implement mkSkill Nix helper + skill CLI

t-780·WorkTask·
·
·
Created7 days ago·Updated7 days ago·pipeline runs →

Description

Edit

Goal

Build a skills packaging system with Nix as the substrate and a skill CLI as the interface.

Architecture

  • Each skill is a Nix derivation using a mkSkill helper
  • skill CLI provides: skill search, skill help, skill tutorial, skill run
  • Registry generated at build time from the flake's package set
  • Per-skill dep isolation (don't monobundle deps)

mkSkill helper (sketch)

mkSkill {
  name = "collagen-protocol";
  deps = [ pkgs.python3 ];
  script = ./run.py;
  description = "Pre-workout collagen timing and dosing protocol";
}

skill CLI subcommands

  • skill search <query> — apropos-style search by keyword
  • skill help <name> — show the markdown instructions
  • skill tutorial <name> — show examples/tutorial section
  • skill run <name> [args] — execute the skill's script
  • skill list — list all available skills

Files likely needed

  • skills/mkSkill.nix — the builder helper
  • skills/flake.nix (or integration with omni flake)
  • skills/skill-cli/main.py (or Haskell/Rust) — the dispatcher
  • Per-skill dirs: skills/foo/README.md, skills/foo/run.py, skills/foo/default.nix

Migration path

  • Existing markdown-only skills stay as-is (no deps = no packaging needed)
  • New skills with deps use mkSkill

Context

Discussed with Ben 2026-04-12. Current pain: skill deps leak into global agent runtime env because there's no per-skill isolation. Skills need executable code, not just instructions. This is the Unix package analogy: binary + man page + apropos.

Timeline (8)

💬[human]7 days ago

New standalone open-source repo on GitHub. Rust CLI for the skill command (portable, no runtime dep). Nix backend for packaging with mkSkill helper. Architecture: skill CLI (Rust, C layer) wraps Nix packages (B layer). Registry generated at build time from flake package set.

💬[human]7 days ago

Additional decisions from Ben (2026-04-12):

  • New standalone open-source repo on GitHub (not inside omni)
  • Rust CLI for the skill binary — small, portable, no runtime deps, works on all platforms
  • Registry format: brew-like at ~/.agents/skills/registry.json (not generated at build time from flake)
  • Skills with no deps: stay as plain markdown, no packaging needed
  • Skills with deps: Nix package using mkSkill helper
💬[human]7 days ago

All skills use mkSkill uniformly — even markdown-only skills are just mkSkill closures with no script/deps. Keeps authoring consistent and avoids a two-tier system.

💬[human]7 days ago

Discovery/registry: use Nix path-resolution instead of a central registry file. skill search scans the flake's package set at query time (same approach as nix search). Can add a local cache (~/.agents/skills/cache.json or similar) for faster lookups later, but the source of truth is always the flake — not a manually maintained registry.json.