skiller

Declarative Agent Skill catalog, configuration, migration, and installation over pinned Vercel Skills.

Commands

skiller catalog configure <alias> --source <source> [--ref <ref>] [--authoring-root <path>]
skiller add-catalog <alias> <source> # compatibility alias
skiller catalog add-skill --root <catalog> --source <skill> --scope <scope> --global|--project
skiller config [-g] [--print] [--set catalog/name=enable|manual|off]
skiller config [-g] --agent <agent> [--agent <agent>...]
skiller update [-g] --check [--json]
skiller update [-g] [--yes]
skiller install [-g]
skiller doctor [-g] [--print|--repair [--yes]]
skiller migrate
skiller migrate --init migration.json
skiller migrate --plan migration.json --check
skiller migrate --plan migration.json --apply [--yes]

catalog configure registers or updates canonical source, ref, and optional explicit owner checkout. Local source and authoring paths may start with ~/ for portable dotfiles configuration. config edits desired selection. update --check reports published and unpublished authoring differences without installation. update requires confirmation and installs canonical catalog content. install performs full canonical reconciliation. doctor diagnoses and explicitly repairs owned state. migrate guides legacy skills into a writable catalog, creates configuration, and optionally installs and cleans exact approved legacy names.

Configuration

Global configuration is ~/.config/skiller/config.json. Project configuration is <project>/skiller.config.json.

{
  "version": 1,
  "catalogs": {
    "pyg": {
      "source": "git@github.com:vlwkaos/skills.git",
      "ref": "main",
      "authoring_root": "/explicit/local/checkout"
    }
  },
  "agents": ["universal", "claude-code", "pi"],
  "skills": {
    "pyg/develop": "enable",
    "pyg/note": "manual"
  }
}

source and optional ref define canonical consumer content. authoring_root is an optional explicit writable checkout used only to detect unpublished owner changes; installation always uses canonical content. At least one Vercel agent is required. Agent names pass to skills@1.5.23, which performs final validation and placement. Project configuration omits catalogs but has the same agents and skills fields.

Enabled skills allow agent and human invocation. Manual skills are human-only unless required. Unselected dependencies are agent-only. Dependency reachability never changes configured selection.

Catalog

{
  "version": 1,
  "scopes": {
    "engineering": { "label": "Engineering", "order": 10 }
  },
  "skills": {
    "develop": { "scope": "engineering", "global": true }
  },
  "renames": {
    "old-develop": "develop"
  }
}

Source and installed names stay clean, such as develop. Skiller adds scope to projected descriptions, such as [engineering] Develop features safely. Pygmalion may still expose $engineering:develop aliases.

Dependencies use comma-separated metadata.skiller.requires. Missing dependencies, cycles, invalid rename chains, eligibility mismatches, symlinks, and selected-name collisions are hard errors.

Safety

• Catalog authoring and migration require an explicit writable checkout and portable source.
• Migration never commits or pushes.
• Legacy cleanup is disabled by default and runs only after verified installation.
• Doctor is read-only unless --repair is supplied.
• Noninteractive mutation requires --yes.
• Skiller removes only prior ownership or exact validated migration/recovery names.
• Installed state is compact schema 3 under the XDG state directory and records deterministic projected-content digests.
• Catalog checks may refresh caches but never install; updates remain confirmation-gated. Unreachable sources are warned once and skipped for that reconciliation; a readable prior cache is shown as read-only stale metadata. config --print, update --check --json, and doctor --print expose a camelCase catalogStatus array with alias, availability/stale state, declared and installed counts, and a sanitized warning.
• Interrupted installation retains an owned transaction journal for Doctor recovery.

The guided migration procedure is also available as skills/skiller-migrate/SKILL.md in this repository.