vskill | Versalist Documentation

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

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 API keys. You also need an active company membership — registry routes reject keys that are valid but have no company.

Variable	Required	Purpose
`VERSALIST_API_KEY`	yes	Sent as x-api-key.
`VERSALIST_BASE_URL`	no	Defaults to https://versalist.com. Point this at staging.
`VSKILL_INCLUDE_PUBLISHED`	no	MCP only. Set to 1 so search_skills includes published-tier skills.

Scope	Commands / tools
`read:skills`	search, pull, status, search_skills, get_skill, report_outcome
`write:skills`	push, suggest

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 a skill into .claude/skills/<slug>/ so Claude Code picks it up. Pins { slug, revision, pulled_at } in ./vskill.lock.

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

vskill push

Publish the skill in the current directory (SKILL.md plus scripts/, references/, assets/). First push creates revision 1. Later pushes need a one-sentence changelog.

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. Fix and push again.

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

Compare vskill.lock pins to the registry. Flags pins behind latest, and pins whose success rate is worse than a newer revision.

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_..." }
    }
  }
}

Keep the key out of the repo

Prefer a host env reference over pasting vk_live_ into a committed JSON file.

API key rules

MCP tools

search_skills

Ranked Skill Exchange matches with descriptions, trigger phrases, and trust signals. Default tier is `verified`. Set `VSKILL_INCLUDE_PUBLISHED=1` to also return `published` skills.

Scope: read:skills

Field	Type	Required	Notes
`query`	string	yes	Matched against name, description, tags, and trigger phrases.
`tags`	string[]	no	Optional tag filter.

get_skill

Download `SKILL.md` and assets. Records a best-effort `load` event.

Scope: read:skills

Field	Type	Required	Notes
`slug`	string	yes	Skill slug, for example `ux-polish`.
`revision`	number	no	Pin a revision. Default is latest.

report_outcome

Report `success`, `failure`, or `abandoned` for a loaded revision. These rates power ranking.

Scope: read:skills

Field	Type	Required	Notes
`slug`	string	yes	Skill slug.
`revision`	number	yes	Revision that was used.
`outcome`	string	yes	`success`, `failure`, or `abandoned`.
`session_ref`	string	no	Opaque session correlation id.

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.

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

Authentication

Commands

vskill search

vskill pull

vskill push

vskill suggest

vskill status

vskill mcp

MCP config

MCP tools

search_skills

get_skill

report_outcome

Registry HTTP

Related