vskill

The package manager for AI skills.
Author. Eval. Publish. Install — across 53 agent platforms.

Download Skill Studio:

All releases: github.com/anton-abyzov/vskill/releases

# Browser studio — zero install
npx vskill@latest studio        # open the local IDE for AI skills
npx vskill@latest install remotion-best-practices

Native Mac, Windows, and Linux desktop apps available at GitHub Releases — 1.5 s cold launch, no telemetry. macOS Apple Silicon is signed by Developer ID Application: EasyChamp, Inc. and notarized + stapled by Apple — no Gatekeeper warning.

The desktop app wraps the same studio runtime as npx vskill studio in a Tauri 2 shell: native menu bar, global ⌘K find-skill palette, ⌘, Preferences with General / Updates / Privacy / Advanced tabs, settings persisted to ~/.vskill/settings.json (atomic, 0600 perms), and signed auto-update via tauri-plugin-updater against minisign-signed manifests.

36.82% of AI skills have security flaws (Snyk ToxicSkills). And the ones that aren't malicious often don't even improve the model — they just feel like they should.

vskill is built around three problems:

• Trust — every install runs a 3-tier scan (58 patterns + hidden-content checks → blocklist → LLM intent). No --skip-scan.
• Proof — Skill Studio runs A/B evals so you can show a skill makes a model better, not assume it.
• Reach — one skill, 53 agents (Claude Code, Cursor, Copilot, Codex, Windsurf, Zed, Gemini CLI, Ollama, …).

npx vskill@latest studio

A localhost workbench opens at a deterministic per-project port. You can:

• Author new skills with an AI-assisted generator (Anthropic skill-creator engine or vskill native — first-class peers, you pick).
• Edit SKILL.md live with a Linear/Raycast-grade UI.
• Run benchmarks with SSE-streamed pass/fail across Claude, GPT, Llama, Gemini, local Ollama / LM Studio.
• A/B compare with vs. without your skill — blind LLM judge ranks outputs as EFFECTIVE / MARGINAL / INEFFECTIVE / DEGRADING.
• Cross-model sweep the same skill across providers (Anthropic Batch API supported — 50% cheaper).
• Find skills from the verified-skill.com registry with a ⌘⇧K palette, install with consent + provenance.
• Publish with one click — git push from the UI, then opens the submit form on verified-skill.com pre-filled.

CORS-free by design: the browser only ever talks to localhost. The server proxies to verified-skill.com and to provider APIs. Every mutation is logged to ~/.vskill/studio-ops.jsonl for audit.

  ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
  │  Source  │────>│   Scan   │────>│  Verify  │────>│ Install  │
  │          │     │          │     │          │     │          │
  │ GitHub   │     │ 58 rules │     │ LLM      │     │ Pin SHA  │
  │ Registry │     │ Blocklist│     │ intent   │     │ Lock ver │
  │ Local    │     │ Patterns │     │ analysis │     │ Symlink  │
  └──────────┘     └──────────┘     └──────────┘     └──────────┘

Every install runs the full pipeline. SARIF v2.1.0 output is available for CI (vskill audit --ci).

# Install one skill
npx vskill@latest install remotion-dev/skills/remotion-best-practices

# Browse a repo, pick interactively
npx vskill@latest install remotion-dev/skills

# Install a Claude Code plugin (full domain bundle)
npx vskill@latest install --repo anton-abyzov/vskill --plugin frontend

Install globally for repeat use: npm i -g vskill

_{Behind a private npm registry? See Getting Started for the E401 workaround.}

Install all eight: npx vskill@latest install --repo anton-abyzov/vskill --all

Browse the full catalog → verified-skill.com/docs/plugins

npx vskill@latest studio               # open local IDE
npx vskill@latest install <skill>      # install with full security scan
npx vskill@latest find <query>         # search verified-skill.com registry
npx vskill@latest list --installed     # what's installed where
npx vskill@latest update --global      # update skills installed with --global
npx vskill@latest doctor --global      # broken links, bad names, lock entries with no files
npx vskill@latest diff <skill> v1 v2   # compare versions before upgrading
npx vskill@latest skill new            # create a new skill (AI-assisted)
npx vskill@latest eval sweep <skill>   # benchmark across models
npx vskill@latest audit --ci           # SARIF v2.1.0 for CI
npx vskill@latest audit-webmcp <url>   # score a site's WebMCP tools (headless)
npx vskill@latest keys set anthropic   # store API keys in ~/.vskill/keys.env
npx vskill@latest auth login --repos   # sign in to GitHub for private skills repos

Full reference → verified-skill.com/docs/cli-reference

# Publish a public skill (repo must be public on GitHub)
npx vskill@latest submit owner/repo --skill my-skill
npx vskill@latest info owner/repo/my-skill          # status, by full name

# Install an exact published version (resolved through the registry to its commit)
npx vskill@latest install owner/repo/my-skill@1.0.0
npx vskill@latest install owner/repo/my-skill --version 1.0.0

# Keep a skill on its version; `vskill pin` prints the matching install command
npx vskill@latest pin my-skill 1.0.0
npx vskill@latest unpin my-skill

# Private publishing (hosted, visible only to your account)
npx vskill@latest submit owner/private-repo --skill my-skill --private --tenant <account>
npx vskill@latest install my-skill --tenant <account> --version 1.0.0

• --version (or @version) installs the commit the registry scanned for that version and pins it; an unknown version exits 1 and lists the published ones.
• The lock records tier: VERIFIED only when the installed SKILL.md matches a published version; otherwise UNSCANNED, and the install names the registry's latest version.
• install <name> -y installs only a skill whose name matches exactly; otherwise it lists the candidates and exits 1.
• Republish: push the SKILL.md change, then run the same vskill submit again. A changed SKILL.md is rescanned and published as a new version; an unchanged one reports the existing result. A rejected submission stays rejected until its SKILL.md changes.
• vskill outdated reports a GitHub-sourced skill as outdated when its SKILL.md upstream differs from the installed one, the same check vskill update makes.

vskill audit-webmcp loads each URL once in headless Chromium with WebMCP turned on, lists the tools the page registers through document.modelContext.registerTool, and scores them. It never calls a tool, never clicks or submits a form, blocks popups and service workers, and refuses downloads.

npx vskill@latest audit-webmcp allbirds.com
npx vskill@latest audit-webmcp --urls-file sites.txt --out report.jsonl --concurrency 4 --fail-on high

Playwright is not bundled. Install playwright-core (or playwright) and a Chromium build with npx playwright install chromium-headless-shell, or pass --executable-path. Without one the command exits 2 with these instructions. Options: --urls-file <path> (one URL per line, # comments), --json, --out <file> (JSON for one URL, JSONL for a batch), --concurrency <n> (default 4), --timeout <ms> (default 30000), --fail-on <severity> (exit 1 when any finding is at or above it), --executable-path <path>.

Tools are found three ways and merged by name: a wrapper around registerTool that records the calling script, the CDP WebMCP domain, and getTools(). Chrome 153 drops consequentialHint from getTools() and CDP, so the wrapper is the only source for it.

Each tool's registeredByKind says who registered it: first-party (the page's site), platform (the hosting platform's own script, with registeredByPlatform), library (a public npm CDN, with registeredByPackage) or third-party; thirdParty is true only for third-party. The platform list is short and only holds what a scan has shown: Shopify's cdn.shopify.com/shopifycloud/ scripts on a page that carries a Shopify storefront marker (window.Shopify.shop, a shopify-digital-wallet or shopify-checkout-api-token meta, or a myshopify.com host). cdn.shopify.com/extensions/ is app code and stays third-party. The report's platforms lists the markers found. Attribution comes from the registering call's stack trace, so it reports where a well-behaved page's code lives; a script that registers through an inline <script> or a //# sourceURL comment can make itself look first-party.

The verdict uses the skill scanner's weights and thresholds (PASS at 80 or above, CONCERNS from 50, FAIL below 50). Each rule deducts at most twice its worst finding, any critical finding is FAIL, and any high finding is at least CONCERNS.

Each site produces one JSON object (schemaVersion: 1); a batch writes one per line and keeps going after timeouts, DNS errors, hung pages and browser crashes, recording error. A site that failed to load with no tools found has summary.verdict: "ERROR" and summary.score: null; a partial load that found tools is scored and keeps error:

{
  "schemaVersion": 1,
  "url": "https://allbirds.com/",
  "finalUrl": "https://www.allbirds.com/",
  "scannedAt": "2026-10-11T06:00:40.000Z",
  "webmcp": { "documentModelContext": true, "navigatorModelContext": false },
  "headers": { "permissionsPolicy": null },
  "platforms": ["shopify"],
  "tools": [{ "name": "proceed_to_checkout", "title": "…", "description": "…", "inputSchema": {}, "annotations": { "readOnlyHint": false }, "registeredBy": "https://www.allbirds.com/cdn/…/webmcp.js", "registeredByKind": "first-party", "thirdParty": false, "sources": ["registerTool", "cdp", "getTools"] }],
  "findings": [{ "id": "WMCP-002", "severity": "high", "tool": "proceed_to_checkout", "message": "…" }],
  "summary": { "toolCount": 12, "readOnlyCount": 4, "consequentialCount": 0, "writeShapedCount": 4, "thirdPartyCount": 0, "platformCount": 0, "libraryCount": 0, "findingsBySeverity": { "critical": 0, "high": 1, "medium": 2, "low": 8, "info": 1 }, "score": 65, "verdict": "CONCERNS" },
  "error": "only present when the page failed to load or timed out"
}

vskill auth signs you in to GitHub using the official Device Flow so the CLI can install skills from private repos and the local Studio can list your org's private catalog.

npx vskill@latest auth login    # interactive Device Flow — copy code, visit URL
npx vskill@latest auth status   # show the current GitHub identity
npx vskill@latest auth logout   # forget all stored tokens
npx vskill@latest whoami        # combined identity + active tenant snapshot

How it works:

1. vskill auth login requests a device + user code from github.com/login/device/code.

2. You visit https://github.com/login/device and enter the 8-character code (rendered as XXXX-XXXX).

3. The CLI polls github.com/login/oauth/access_token until you authorize, then validates against api.github.com/user.

4. The CLI calls POST /api/v1/auth/github/exchange-for-vsk-token to mint a verified-skill API token (vsk_…) scoped to the same identity.

5. Both tokens are stored in your OS keychain (macOS Keychain / Windows DPAPI / libsecret) under distinct service names:

   • com.verifiedskill.desktop / github-oauth-token → gho_… (raw GitHub OAuth)
   • com.verifiedskill.desktop / vskill-token → vsk_… (verified-skill API token)

   On systems without a keyring daemon, both fall back to ~/.vskill/keys.env with mode 0600 and a startup warning.

If the exchange step fails (network error, 5xx), login still succeeds with just the gho_… token and the CLI prints Logged in (legacy mode — some features unavailable). Re-run vskill auth login later to mint the vsk_… token without losing your session.

Where the tokens are used:

• vskill add <skill>, vskill list, vskill marketplace — every request to verified-skill.com carries Authorization: Bearer <vsk_… or gho_…> (preferring vsk_ when present). Anonymous requests for public skills still work when no token is stored.
• vskill install <github-url> — added as Authorization: Bearer … on every fetch to api.github.com and raw.githubusercontent.com. Public skills still install anonymously.
• vskill studio — the local eval-server proxies private routes (/api/v1/private/*, /api/v1/tenants/*) to verified-skill.com with the bearer header injected at the proxy boundary. Your browser never holds the token.

Configuration:

• VSKILL_GITHUB_CLIENT_ID — the OAuth/App client_id used during Device Flow. Defaults are baked in for the public Skill Studio App; set this only if you are running a self-hosted variant.
• VSKILL_TENANT — overrides the active tenant for a single invocation (CI / scripted use). See "Tenant resolution priority" below.

Inspect status of all credentials in one place:

npx vskill@latest keys list      # shows AI provider keys + the github slot
npx vskill@latest whoami         # email, token prefix, active tenant, all tenants

When your GitHub identity belongs to multiple organizations that have the Skill Studio App installed, each org is a tenant in verified-skill.com. The CLI calls them "orgs" for symmetry with gh org, gcloud config configurations, and kubectl config use-context.

npx vskill@latest orgs list           # table: slug | name | role | active (* marks the active tenant)
npx vskill@latest orgs use <slug>     # write currentTenant to ~/.vskill/config.json
npx vskill@latest orgs current        # print the active tenant slug, or `(none)`

orgs and whoami are anonymous-safe — running them without a stored token prints Not logged in. Run \vskill auth login`.` and exits non-zero (orgs returns 0; whoami returns 1) without crashing.

When a tenant-scoped command (vskill add, vskill install for a private skill, etc.) needs to pick an active tenant, it walks this list in order — first match wins:

1. --tenant <slug> flag — per-command override (highest precedence).
2. VSKILL_TENANT env var — non-interactive / CI use.
3. currentTenant in ~/.vskill/config.json — the persistent active tenant set by vskill orgs use or the Studio sidebar picker.
4. Auto-pick when N=1 — if you belong to exactly one tenant, that one is used silently.
5. Error — if you belong to N>1 tenants and none of (1)–(3) is set, the CLI prints Multiple tenants available — set one with \vskill orgs use `.` and exits non-zero. The CLI never silently picks one of N>1.

The same ~/.vskill/config.json is shared with Skill Studio — switching tenants in Studio's sidebar picker updates the same file the CLI reads, so the two surfaces stay in sync.

When you run vskill add <skill>, the resolver tries:

1. The public registry.
2. The active tenant's scoped registry (resolved via the priority above).
3. Other tenants you belong to, in parallel HEAD requests — first match wins.

If a --tenant <slug> flag is set, only the public registry and that tenant are tried.

Common error messages:

• Skill found in multiple tenants: acme, contoso. Re-run with --tenant <slug> or set an active tenant: vskill orgs use <slug>. — ambiguity guard for N>1 with no active tenant.
• Authentication failed. Run \vskill auth login` to re-authenticate.` — the registry returned 401. The keychain is not auto-cleared (you might be on a flaky network).
• Upgrade required: <message> (<upgradeUrl>) — the registry returned 402: skill exists in this tenant but you lack entitlement.

Once authenticated, installing a private org skill is identical to a public one — the CLI silently attaches the keychain token to every request:

npx vskill@latest auth login                                # one-time setup (mints gho_ + vsk_)
npx vskill@latest orgs use acme                             # pick a tenant if you belong to multiple
npx vskill@latest add private-skill                         # private skill installs same as public

The local skill bundle on disk never contains your GitHub token — the token is used only at fetch time. Your project's vskill.lock records source: "private" and the org name so future updates re-authenticate correctly.

A team can keep its skills in a private GitHub repo and install them like public ones. Sign in with vskill auth login --repos (or gh auth login, or GITHUB_TOKEN), then:

npx vskill@latest install acme/team-skills/onboarding      # one skill
npx vskill@latest install --repo acme/team-skills --all    # everything in marketplace.json

Skills from a private repo are never reported to verified-skill.com, and vskill update only ever reads them from that repo. Walkthrough: docs/private-skills-repo.md.

Skill Studio private-repo support (increment 0826) ships with documented threat model, verification checklist, SOC 2 evidence map, and operational runbooks — all in the umbrella repo under .specweave/docs/:

• Customer quickstart — .specweave/docs/external/private-repos-quickstart.md
• Vendor security questionnaire — .specweave/docs/external/security-questionnaire-template.md
• Threat model & verification checklist — .specweave/docs/internal/security/0826-*.md
• SOC 2 evidence map — .specweave/docs/internal/compliance/0826-soc2-evidence-map.md
• Operations + rotation runbooks — .specweave/docs/internal/runbooks/0826-*.md

• 0.5.129 — Studio Publish: one-click git push + open verified-skill.com submit pre-filled
• 0.5.12x — Studio Find palette (⌘⇧K): search the registry from inside Studio
• 0.5.11x — Engine selector in Create flow: choose Anthropic skill-creator or vskill native
• 0.5.10x — Multi-project tabs, deterministic per-project port (3077–3177), bookmarkable URLs
• 0.5.0x — A/B comparison with blind LLM judge, cross-model sweep, MCP-skill simulation mode

Full changelog → github.com/anton-abyzov/vskill/releases

Issues and PRs welcome at github.com/anton-abyzov/vskill. To submit a skill to the registry, see verified-skill.com/docs/submitting.

Inside this repo dependency install scripts are disabled (.npmrc): run npm ci, then npm run setup (rebuilds esbuild), and npm run security:scan before pushing — see SECURITY.md.

MIT