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. config --print also reports machine-local authoring provenance and whether it is the canonical source. update --check reports published and unpublished authoring differences without installation. update requires confirmation and installs canonical catalog content. install performs full canonical reconciliation, including safe rename repair, exact-content adoption, independent progress, and inline owned recovery. 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.
• Installed skill directories are read-only projections. Skills write only to explicit project, XDG state/cache, or catalog authoring paths; Skiller remains the projection writer.
• Interrupted installation retains an owned transaction journal that a later install resumes when its scope and desired names still validate.
• Vercel listing is bounded to 15 seconds and placement to 60 seconds. Permission, sandbox, network, timeout, placement, and state failures are reported separately without speculative ownership advice.

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