vskill

@versalist/vskill talks to the Skill Exchange registry. It is a different package from @versalist/cli. Conceptual bundle workflow stays on skill bundles.

Use Node.js 20 or newer. The current client dependency requires this minimum version.

When the package is available in your configured registry, use one of these commands:

npm install -g @versalist/vskill
# or
npx -y @versalist/vskill help

Authentication

Same key header as the rest of the platform: x-api-key. Create the key at Developer API. You also need an active company membership — registry routes also enforce current account approval and reject keys without an active company.

Commands

vskill search

Ranked search with tier, recent loads, success rate, and last updated.

vskill search "code review" --tags review,quality --tier verified
vskill search "ux" --json

vskill pull

Download local files into .claude/skills/<slug>/ beneath the current directory or --dir. Download success does not establish agent execution. vskill.lock stays in the process working directory, including with --dir. Each lock entry identifies the registry, company, bundle, destination, version, and managed file digests. The registry must provide company, bundle, and version identities. Older responses without these fields cannot create an installation. Pull validates and stages the complete update before replacement. Separate destinations retain separate file manifests. Pull preserves untracked files and rejects local conflicts. Back up conflicting files before using --overwrite-local.

vskill pull ux-polish@4
vskill pull ux-polish@4 --dir ~/projects/app
# After reviewing and backing up local changes:
vskill pull ux-polish@4 --overwrite-local
# Only use @4 if it is the actual published revision reported by the registry.
# Unpinned API-key pull selects latest_verified and fails without a current registry review.

Recovery and legacy locks

If an update stops, run vskill recover from the directory containing its lock. Recovery needs no API key. Keep the transaction journal and hidden backup directories until recovery completes. A committed lock retains the new installation. An uncommitted update restores the previous installation. If files changed after interruption, recovery stops for inspection.

Version-1 locks cannot establish destination ownership. Inspect the installation before using --reconcile-legacy. This option records the selected destination and preserves old files without proven ownership. If content differs, back it up before adding --overwrite-local. Other local copies remain untouched. Archive and membership changes cannot recall downloaded files.

vskill recover
vskill pull ux-polish@4 --dir ~/projects/app --reconcile-legacy

vskill push

Publish the skill in the current directory (SKILL.md plus scripts/, references/, assets/). First push creates the first revision. Company/tool policy can keep it pending review. Later pushes need a one-sentence changelog and may become pending suggestions instead of publications. Read the saved tier, state, revision and approval flag; success alone is not publication.

vskill push
vskill push --slug ux-polish --changelog "Tighten the contrast checklist."
vskill push --draft

Lint failures print as field-level issues from the registry linter. Drafts are visible to their owner, authorized reviewers, workspace admins/owners and active collaborators. --draft is only for new slugs. First review-required publication appears in the workspace review queue. Published local copies remain unchanged until you explicitly pull. With local assets, push/suggest sends a full replacement set; without them, it retains published assets.

Supported content

Push and suggest accept UTF-8 text in SKILL.md, scripts/, references/, and assets/. The client rejects binary files, invalid UTF-8, symlinks, and unsupported root members before upload. The asset limit is 50 files. Each asset can contain 256 KiB. Total content can contain 1 MiB. The client preserves supported text bytes and line endings.

This format cannot preserve evals/, BENCHMARK.md, skill-card.md, or skill.oms.sig. Move unsupported material outside the upload directory. The client excludes .git, .gitignore, and vskill.lock as local administration files. Installation paths must not contain symlinks. Use the physical directory path when an operating-system alias is a symlink.

Standard allowed-tools strings separate declarations with spaces. The client preserves restrictions such as Bash(git:*). YAML string lists and legacy comma-separated declarations are also accepted. Company policy controls capability availability. A declaration does not grant execution permission.

allowed-tools: Bash(git:*) Bash(jq:*) Read

vskill suggest

Propose the current directory as a revision of someone else's skill.

vskill suggest ux-polish --changelog "Add a focus-ring audit step."

vskill status

Status checks installed file digests and the registry, company, bundle, and version identities. It compares each installation with published revision history. Update commands include the destination and an explicit revision. Local changes, legacy pins, missing identities, and unavailable distribution remain warnings.

vskill status

vskill mcp

vskill mcp
npx -y @versalist/vskill mcp

With no arguments over a non-TTY stdio (how MCP hosts spawn servers), vskill starts this mode automatically.

MCP config

{
  "mcpServers": {
    "vskill": {
      "command": "npx",
      "args": ["-y", "@versalist/vskill", "mcp"],
      "env": { "VERSALIST_API_KEY": "vk_live_..." }
    }
  }
}

MCP tools

VSKILL_INCLUDE_PUBLISHED=1 only widens discovery. It does not change get_skill retrieval: pass the actual published revision to load a publication without verification.

Registry HTTP

The CLI is the supported interface. The same key authenticates /api/skills/registry/* when you need HTTP:

• GET /api/skills/registry — search (read:skills)
• GET /api/skills/registry/:slug/pull — download a bundle (read:skills)
• POST /api/skills/registry — publish revision 1 (write:skills)
• POST /api/skills/registry/:slug/versions — publish the next revision
• POST /api/skills/registry/:slug/events — load / outcome telemetry

Endorse, verify, archive, share, bindings, collaborators, and discussions exist on the same prefix. Use them from the web app unless you are building against a specific route. Maintenance (POST /api/skills/registry/maintenance) is internal — it uses a secret header, not your user key.

Related

• Skill bundles — what a bundle contains and when to promote a version.
• API keys — create read:skills / write:skills.
• Versalist MCP server — challenge tools on @versalist/cli.