# 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`):

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

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

   ```nix
   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):

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

4. **Lock child AND parent** (both steps required):
   ```bash
   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

```bash
# 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](https://github.com/harlan-zw/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:

   ```bash
   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:

   ```bash
   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/`.