skiller

skiller declaratively selects skills from registered catalogs and delegates final project or global placement to pinned Vercel Skills.

Commands

skiller add-catalog pyg vlwkaos/skills
skiller config [--print] [--set catalog/name=enable|manual|off]
skiller install [--migrate]
skiller config -g [--print] [--set catalog/name=enable|manual|off]
skiller install -g [--migrate]

Interactive config opens a scoped terminal UI: arrows navigate, Space cycles Agent + Human, Human, and Off, i toggles project Git-ignore state, and s or Enter saves. Escape or q cancels without writing.

--print emits machine-readable catalog, selection, dependency, and installed state without prompting or changing configuration/installation state; remote catalog refresh may update Skiller's cache. --set applies one or more validated selections without installing, so a frontend can save once and then run skiller install. --migrate adopts same-name legacy installations only after every selected source stages successfully. Unrelated skills remain untouched.

Configuration

Project selections live in <project>/skiller.config.json:

{
  "version": 1,
  "skills": {
    "pyg/develop": "enable",
    "pyg/private-workflow": {
      "mode": "manual",
      "gitignore": true
    }
  }
}

Global catalog registration and selection share ~/.config/skiller/config.json:

{
  "version": 1,
  "catalogs": {
    "pyg": { "source": "vlwkaos/skills" }
  },
  "skills": {
    "pyg/develop": "enable",
    "pyg/note": "manual"
  }
}

The global file may be symlinked from dotfiles. Runtime ownership stays outside dotfiles under ${XDG_STATE_HOME:-~/.local/state}/skiller/installed.json.

• enable: normal Agent Skills discovery.
• manual: adds supported explicit-invocation controls.
• gitignore: omits that project skill's Vercel projections from Git.
• Omitted entries are not selected. Required dependency closure is installed automatically.

Catalog format

Catalogs use flat source names and optional organizational metadata:

skills/develop/SKILL.md
skills/commit/SKILL.md
skiller.json

{
  "version": 1,
  "scopes": {
    "engineering": { "label": "Engineering", "order": 10 }
  },
  "skills": {
    "develop": { "scope": "engineering", "global": true },
    "commit": { "scope": "engineering", "global": false }
  }
}

Global configuration shows only global: true skills. Project configuration shows only project skills. Global names remain unchanged; project names receive their display-scope postfix, such as develop-engineering.

Dependencies use a comma-separated string in metadata.skiller.requires. Missing targets and cycles fail catalog loading. Global dependency closure must also be global.

Installation and ownership

Skiller stages untrusted catalog content through skills@1.5.23, rejects symlinks and invalid names, applies naming/manual transforms, then invokes Vercel Skills again as the final writer with explicit universal, claude-code, and pi targets. Vercel creates the canonical Agent Skills store and Claude Code/Pi projections.

Project ownership lives in .skiller/installed.json; global ownership lives in the XDG state path. Removal passes only previously owned names to Vercel Skills. Skiller never removes unrelated skills.

New machine

1. Install Skiller through Homebrew or Cargo.
2. Apply dotfiles so ~/.config/skiller/config.json points to the tracked global configuration.
3. Run skiller install -g on a clean machine.
4. Run skiller install -g --migrate when replacing legacy global skill roots.
5. In each project, run skiller install or skiller install --migrate once for legacy project layouts.

--migrate unlinks legacy vendor root symlinks without deleting their source tree, then lets Vercel recreate per-skill links.