skiller
Declarative Agent Skill catalogs and convergent project/global installation over pinned Vercel Skills.
Commands
Run bare skiller to choose Project or Global configuration. Saving interactive configuration and applying config --set or --agents immediately reconcile the matching installation. Piped read-only config remains inspection-only. Explicit install remains available for recovery and automation.
STATE is enable, manual, enable-ignored, manual-ignored, or off. Project is the safe default for new catalog skills; --global is explicit. Project and global eligibility are exclusive, so globally catalogued skills never appear in project configuration. An explicit off may remove an existing selection whose catalog eligibility later changed.
Read-only commands choose output automatically. A TTY gets the organized interactive or human view with semantic color and status icons; NO_COLOR and TERM=dumb disable styling. A pipe, agent, or subprocess gets compact one-line JSON where supported and plain output otherwise. Interactive config and mutating config --set or --agents refresh catalogs; piped read-only config and doctor use synchronized cache only. Failed config refreshes show cached catalog entries as read-only with recovery guidance. update and install retain their explicit reconciliation roles. Global update checks the stable Skiller release without blocking skill results when the registry is unavailable, and reports a newer binary without installing it.
Configuration
Skiller keeps policy and generated state outside the tracked worktree:
| Data | Path | Scope |
|---|---|---|
| Global configuration | ~/.config/skiller/config.json |
Device |
| Project configuration | $(git rev-parse --git-common-dir)/skiller/config.json |
Repository clone, shared by linked worktrees |
| Project installation state | $(git rev-parse --git-dir)/skiller/installed.json |
Current worktree |
| Installed projections | <worktree>/.agents/skills/ and agent-native equivalents |
Current worktree |
Project mode requires Git. Outside a repository, bare skiller opens Global configuration directly.
Canonical source and optional ref own consumer content. authoring_root is an optional writable checkout used for guidance and unpublished-draft checks. Installation always uses canonical content.
Interactive configuration restores the pre-Skiller selector geometry. Wide terminals keep scope navigation, compact one-line skill/configuration rows, and selected description, package-manager-style install plan, reverse dependents, installed state, and sync details visible in three columns. Enter moves focus from scopes to skills; Escape moves back. A persistent action bar exposes Save (S) and direct Cancel (Q). Narrow terminals retain the same scope-first navigation, stack only the selected skill's labeled details, and preserve both global actions before contextual hints. Semantic scope, dependency, mode, recommendation, warning, error, focus, and action colors remain stable and respect NO_COLOR and TERM=dumb. Redraws queue one synchronized frame and replace rows in place instead of blanking the alternate screen.
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.
Every install prints an aligned plan before any projection mutation: one row per resolved skill, tree branches for dependency edges, and two trailing columns for access (Agent + Human, Human only, or dependency) and change (new, update, or current). The heading carries the totals, and skills that are no longer desired are listed under a separate Remove heading. Skill names are shown without their catalog prefix, and a dependency that is also configured directly shows its configured mode.
Catalog skills carry a content digest rather than a semantic version, so update means the authoritative content differs from the installed baseline. Interactive configuration reports the same pending updates in its header while catalogs are refreshed.
Project reconciliation
Catalog-managed installations are read-only, disposable projections. The catalog is authoritative.
| Status | Meaning | Install behavior |
|---|---|---|
synced |
Projection matches the installed catalog tree | No content change |
missing |
An owned projection is absent | Reinstall it |
drift |
Projection differs from authoritative content or lacks an old baseline | Overwrite it |
incoming |
Catalog identity, mode, or metadata changed | Install the new projection |
To change a managed skill, edit its catalog authoring source, publish it, then run skiller config or skiller install. Skiller does not preserve project overrides or merge projection edits. A divergent unowned same-name skill remains protected; byte-identical unowned projections are adopted safely.
A divergent unowned name blocks noninteractive installation and is reported as [unowned-conflict]. When installation runs in a terminal, Skiller lists each conflict and asks per skill: y replaces that name with the catalog version, Y replaces every remaining conflict, and any other answer keeps the existing copy. An unanswered prompt, EOF, and every automated or piped run keep the existing copy, so replacement only happens through explicit interactive approval.
On the first mutating Project command, Skiller imports legacy <project>/skiller.config.json and <project>/.skiller/ data. It removes untracked legacy files after successful migration. A tracked or divergent legacy config remains for explicit review but is ignored once the Git-private config exists.
Project Skills lock
Skiller catalog skills are owned only by the current worktree's Git-private skiller/installed.json; native project skills added directly through Vercel Skills are owned only by skills-lock.json. Before and after Vercel placement, reconciliation removes only state-proven Skiller entries whose source resolves to the current Git-private skiller/prepared-current and preserves every native entry. Skills 1.5.23 add, install, sync, and named removal do not prune unrelated projections.
Catalog
skiller.json declares semantic scopes, eligibility, and renames. Skill frontmatter declares comma-separated dependencies through metadata.skiller.requires and optional deterministic project recommendations. Missing dependencies, cycles, invalid rename chains, eligibility mismatches, symlinks, and installed-name collisions are hard errors.
Catalog recommendations
A project-only skill may declare metadata.skiller.recommend.files: "Cargo.toml" and metadata.skiller.recommend.keywords: "release,Homebrew" in SKILL.md. Values are literal: files match exact root names, keywords match case-insensitively in root names plus the first 20 KB of package.json, pyproject.toml, Cargo.toml, README.md, and AGENTS.md. Alternatives within one field are OR; populated fields combine with AND. Config JSON returns exact recommendedBy reasons, and the TUI marks matching scopes and skills without selecting or installing them.
catalog add-skill resolves the alias's validated authoring checkout. It no longer accepts an arbitrary catalog root. Legacy migration uses the bundled skiller-migrate guidance with normal catalog, config, and install commands.
Doctor and recovery
skiller doctor [-g] is read-only. Its human report groups ownership conflicts by skill and maps catalog freshness, projection drift, project Skills lock entries, and owned-state problems to explicit actions. skiller install [-g] adopts byte-identical unowned skills automatically; divergent content stays unchanged and Doctor shows the exact command to keep the existing owner. Non-TTY Doctor JSON remains deterministic and does not include presentation-only recommendations. Repair still requires --repair and confirmation unless --yes is supplied.
Safety
- Skiller removes only verified ownership or exact approved recovery names.
- Unowned projections are adopted only when every discovered copy is byte-identical.
- Installed state is compact schema 4 and records catalog identity plus the authoritative content baseline.
- Install resumes only validated interrupted transactions and retains independent per-skill progress.
- Catalog-owned project and global projections are overwritten from authoritative content.
- Tracked legacy configuration is never deleted automatically; migrated legacy paths stop competing as readers.
- Vercel listing is bounded to 15 seconds and placement to 60 seconds.
- Git SSH acquisition is bounded and repeated unreachable sources are suppressed briefly.
- Permission, process, network, timeout, placement, and state failures are classified separately.
- Mutation remains explicit:
update --yes,doctor --repair, anddoctor --repair --yesfor reviewed automation.
Skiller pins skills@1.5.23 for final validation and placement.