CLI

Install

npm install -g @skillist/cli

Package: @skillist/cli

Authentication

The CLI authenticates with an org API key — there is no interactive sign-in command. Create a key under Settings in the console, then export it:

export SKILLIST_API_KEY=sk_...

Keys are shown once at creation and stored hashed. Each carries explicit scopes and is refused outside them.

Reads of public skills (search, install, pull) work without a key. A key is required by: push, publish, eval, run, rollback, mcp proxy, inventory scan, inventory import, inventory list, and required-skills check.

Registry

Skills are referenced as org/repo (GitHub-style), optionally pinned to an exact published version with @:

skillist search <query> [--category <cat>] [--tag <tag>]
skillist install <org>/<repo>            # latest, resolved then pinned
skillist install <org>/<repo>@1.2.3      # exact version (immutable)
skillist pull <org>/<repo>[@version]
skillist list

Installs resolve to an exact version, download over the immutable versioned URL, and verify the bundle’s SKILL.md against the registry’s published sha256 (recorded in .skillist.lock as contentSha256). skillist update checks the current published version first and skips skills that are already up to date.

Public delivery URLs default to https://skillist.io/{org}/{repo}:

curl https://skillist.io/skillist/web-perf-audit/SKILL.md

Sync

skillist sync materializes the lockfile into every agent harness directory in the project, so one pinned set of skills is delivered to Claude Code, Cursor, Codex, Gemini, VS Code, and .agents/ at once:

skillist sync                  # reconcile every detected harness
skillist sync --check          # plan only; exits 1 on drift (CI gate)
skillist sync --prune          # also remove skills no longer in the lockfile
skillist sync --force          # overwrite locally-modified skills

Targets are detected from the harness root: .claude/ present means .claude/skills is written. Pass --target <dir> (repeatable) to override, --scope user to reconcile $HOME instead of the project, and --link symlink to link to the local store rather than copy.

An optional skillist.json declares the desired set, including version ranges and directory aliases. Without it, sync uses .skillist.lock as-is:

{
  "version": 1,
  "org": "acme",
  "skills": [
    { "ref": "skillist/web-perf-audit", "version": "^1.0.0" },
    { "ref": "acme/deploy-runbook", "version": "2.0.1", "as": "deploy" }
  ]
}

Bundles are cached once in .skillist/store/ and copied out to each target. .skillist/manifest.json records every path sync owns — a skill sync did not write is reported as untracked and is never modified or pruned, and a managed skill you have edited locally is reported as a conflict rather than silently overwritten. Add .skillist/ to .gitignore; commit .skillist.lock, skillist.json, and the materialized skill directories so a fresh clone works without running sync, with skillist sync --check in CI to catch divergence.

Two version ranges are supported, ^x.y.z and ~x.y.z, plus exact versions and latest. Because delivery publishes only the latest version, a range resolves against it and errors if latest falls outside the range — pin an exact version in that case.

When SKILLIST_API_KEY is set, each materialization reports an activation event tagged with the harness and scope it landed in, so the console can show which harnesses a skill is actually live in. The report is best-effort — sync never fails because telemetry did — and repeated events from one actor move the public ranking counters at most once per day per skill.

Publishing

From a skill directory with plugin.json and SKILL.md:

skillist push <org>/<repo> <dir>
skillist publish <org>/<repo> <dir> [--bump major|minor|patch]

Publishing queues an eval run. Your org policy may require a passing eval before the version goes live.

Sandbox runs

For skills with hosted runtime scripts:

skillist run <org>/<repo> --script scripts/<name> [--stream]

Requires SKILLIST_API_KEY with the skills:run scope — the CLI sends it as a Bearer token, and runs without one are rejected with 401. Anonymous sandbox runs are not permitted. See Sandbox execution.

Review & inventory

Quality/security gate for CI (see Install policy):

skillist review ./my-skill --threshold 80 --fail-on high --json

Discover local agent skills and sync estate inventory (see Skill inventory):

export SKILLIST_API_KEY=sk_...
skillist inventory scan --org my-org
skillist inventory import --github-org my-github-org --org my-org
skillist inventory list --org my-org

Installs and updates respect org install policy when SKILLIST_API_KEY is set.

Environment

Variable	Default	Description
SKILLIST_API_URL	https://api.skillist.io	REST API and auth base URL
SKILLIST_DELIVERY_URL	https://skillist.io	Public skill pages and SKILL.md delivery
SKILLIST_API_KEY	—	Bearer token (sk_...) for push, publish, and private runs

Local development:

export SKILLIST_API_URL=http://localhost:8787
export SKILLIST_DELIVERY_URL=http://localhost:5173

Commands

• skillist search [query] — search registry with filters
• skillist install <org>/<repo>[@version] — download, verify sha256, and record in .skillist.lock
• skillist pull <org>/<repo>[@version] — download without lockfile
• skillist push <org>/<repo> <dir> — upload draft version
• skillist publish <org>/<repo> <dir> — push and publish
• skillist run <org>/<repo> --script <path> — hosted execution
• skillist eval <org>/<repo> [--wait] — queue skill eval on latest draft
• skillist rollback <org>/<repo> <semver> — roll back to a previous version
• skillist update [org/repo] — refresh installed skills
• skillist sync [--check] [--prune] [--force] — materialize the lockfile into every agent harness directory
• skillist review <dir> [--threshold N] [--fail-on sev] [--json] — quality + security CI gate
• skillist required-skills check [--org <slug>] — verify lockfile against required skills
• skillist inventory scan [--org <slug>] — BFS-discover local skills and POST inventory scan
• skillist inventory import --github-org <org> — scan a GitHub org via gh and POST inventory
• skillist inventory list [--org <slug>] — list org skill inventory
• skillist mcp proxy <org>/<name> — stdio proxy to an org MCP gateway