Skills Catalog (Child Flake)

Manages shared global skills via agent-skills-nix.

How It Works

skills/flake.nix is a child flake (separate lock file). It defines:

1. Sources — where skills come from (local dir or remote repos)
2. Skill selection — which skills to enable
3. Targets — where skills are installed (symlink-tree into ~/.agents/skills/; Codex, Pi, OpenCode, and Hermes read there directly; Claude gets a compatibility bridge via ~/.claude/skills/)

Hermes note: Hermes builtin skills do not include these dotfiles shared skills by default. In this repo, Hermes picks them up through skills.external_dirs pointing at ~/.agents/skills. If that external dir wiring is missing, Hermes falls back to builtin-only skills.

Adding a Local Skill

Drop a directory with SKILL.md into config/agents/skills/<name>/. Auto-enabled via skills.enableAll = ["local"].

Adding a Remote Skill

1. Add flake input (hash-pinned, flake = false):

   my-repo = {
     url = "github:org/repo";
     flake = false;
   };
   

2. Add source with subdir pointing to the skills parent directory:

   sources.my-repo = {
     path = inputs.my-repo.outPath;
     subdir = "path/to/skills";  # parent of skill dirs
     filter.maxDepth = 2;
   };
   

3. Add explicit skill entry (name = skill dir inside subdir):

   skills.explicit = {
     my-skill.from = "my-repo";
     my-skill.path = "my-skill";  # dir name under subdir
   };
   

4. Lock child AND parent (both steps required):

   cd skills && nix flake lock --update-input my-repo
   cd .. && nix flake update skills-catalog
   

⚠️ CRITICAL: Whenever you change skills/flake.nix or skills/flake.lock, you MUST also run nix flake update skills-catalog from the repo root to sync the parent lock. Forgetting this causes attribute 'xxx' missing errors at rebuild time.

Updating Remote Skills

# Update child lock
cd skills && nix flake update  # update all
cd skills && nix flake lock --update-input openai-skills  # update one

# THEN sync parent lock (REQUIRED)
cd .. && nix flake update skills-catalog

Then hey rebuild.

Adding a skilld-Generated Skill

skilld generates SKILL.md files from npm package docs. To add one to the Nix-managed catalog:

1. Generate the skill in a temp directory:

   cd /tmp && mkdir skilld-gen && cd skilld-gen
   npm init -y && npx skilld add <package> --agent claude-code -y
   

2. Copy the SKILL.md into local skills:

   cp .claude/skills/<generated-name>/SKILL.md \
     config/agents/skills/<package>/SKILL.md
   

   Skip the .skilld/ symlinks — they point to runtime caches. The SKILL.md itself tells agents to use npx -y skilld search for lookups.

3. Rebuild: hey rebuild — auto-enabled via local source.

Marimo Skill Curation

We intentionally do not enable every skill from marimo-team/skills.

Kept:

• marimo-notebook — core notebook authoring conventions
• jupyter-to-marimo — common migration path
• streamlit-to-marimo — common migration path
• anywidget — richer custom widget/UI work
• wasm-compatibility — useful validation niche
• implement-paper — interactive, user-steered paper workflow
• marimo-pair — separate repo; main live-notebook pairing capability

Removed from the enabled set:

• add-molab-badge — niche publishing helper; not broadly useful during normal coding flows
• auto-paper-demo — overlaps with implement-paper, but forces a no-feedback workflow
• implement-paper-auto — overlaps heavily with implement-paper; we prefer the interactive version
• marimo-batch — valid, but narrower than the core authoring/conversion skills we want loaded by default

Rule of thumb: prefer broad, reusable skills with low overlap. Avoid installing narrow helpers or duplicated "auto" variants unless we repeatedly need them.

Discovering Current Sources

List inputs: nix flake metadata skills/ --json | jq -r '.locks.nodes.root.inputs | keys[]'. Skill source/mapping config lives in skills/flake.nix (sources and skills.explicit blocks). Local skills are auto-discovered from config/agents/skills/.