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
```bash
# 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](https://github.com/anton-abyzov/vskill/releases/latest)** — 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.
## Why vskill
**36.82% of AI skills have security flaws** ([Snyk ToxicSkills](https://snyk.io/blog/toxicskills-malicious-ai-agent-skills-clawhub/)).
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 (52 patterns → 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, …).
## Skill Studio — the local IDE for skills
```bash
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.
## How install works
```
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Source │────>│ Scan │────>│ Verify │────>│ Install │
│ │ │ │ │ │ │ │
│ GitHub │ │ 52 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`).
## Quick Start
```bash
# 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.
## What ships today
| Surface | Count | Notes |
|---|---|---|
| **Agent platforms** | **53** | Claude Code, Cursor, Copilot, Windsurf, Codex, Gemini CLI, Zed, Ollama, LM Studio, … |
| **Plugins** | **8** | Multi-skill bundles for Claude Code |
| **Skills** | **14** | Individual SKILL.md files inside plugins |
| **Top-level CLI commands** | **22** | `install`, `studio`, `eval`, `find`, `scan`, `audit`, `submit`, `skill`, `keys`, … |
| **Tests** | **307 test files** | More tests than source files |
### Plugins (Claude Code)
| Plugin | Skills |
|---|---|
| **frontend** | figma-connect, frontend-design, task-skill-announcer |
| **personal** | obsidian-brain, greet-anton, tax-filing |
| **marketing** | slack-messaging, social-media-posting |
| **skills** | skill-builder, scout |
| **mobile** | appstore |
| **google-workspace** | gws |
| **easychamp** | tournament-manager |
| **productivity** | survey-passing |
Install all eight: `npx vskill@latest install --repo anton-abyzov/vskill --all`
Browse the full catalog → [verified-skill.com/docs/plugins](https://verified-skill.com/docs/plugins)
## Commands you'll actually use
```bash
npx vskill@latest studio # open local IDE
npx vskill@latest install # install with full security scan
npx vskill@latest find # search verified-skill.com registry
npx vskill@latest list --installed # what's installed where
npx vskill@latest diff v1 v2 # compare versions before upgrading
npx vskill@latest skill new # create a new skill (AI-assisted)
npx vskill@latest eval sweep # benchmark across models
npx vskill@latest audit --ci # SARIF v2.1.0 for CI
npx vskill@latest keys set anthropic # store API keys in ~/.vskill/keys.env
npx vskill@latest auth login # sign in to GitHub for private skills
```
Full reference → [verified-skill.com/docs/cli-reference](https://verified-skill.com/docs/cli-reference)
## Authentication (GitHub, for private skills)
`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.
```bash
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 `, `vskill list`, `vskill marketplace`** — every request to `verified-skill.com` carries `Authorization: Bearer ` (preferring `vsk_` when present). Anonymous requests for public skills still work when no token is stored.
- **`vskill install `** — 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:
```bash
npx vskill@latest keys list # shows AI provider keys + the github slot
npx vskill@latest whoami # email, token prefix, active tenant, all tenants
```
### Tenants and `vskill orgs`
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`.
```bash
npx vskill@latest orgs list # table: slug | name | role | active (* marks the active tenant)
npx vskill@latest orgs use # 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.
#### Tenant resolution priority
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 ` 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.
#### `vskill add` resolution order (private skills)
When you run `vskill add `, 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 ` 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 or set an active tenant: vskill orgs use .` — 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: ()` — the registry returned 402: skill exists in this tenant but you lack entitlement.
### Private skill workflow
Once authenticated, installing a private org skill is identical to a public one — the CLI silently attaches the keychain token to every request:
```bash
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.
Customer-facing setup walkthrough → [`.specweave/docs/external/private-repos-quickstart.md`](../../../.specweave/docs/external/private-repos-quickstart.md) (in the umbrella repo).
## Security & Compliance
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`
## Recent highlights (0.5.x)
- **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](https://github.com/anton-abyzov/vskill/releases)
## Learn more
| Topic | Where |
|---|---|
| Quick start & first install | [verified-skill.com/docs/getting-started](https://verified-skill.com/docs/getting-started) |
| Full CLI reference | [verified-skill.com/docs/cli-reference](https://verified-skill.com/docs/cli-reference) |
| Security model & 3-tier verification | [verified-skill.com/docs/security-guidelines](https://verified-skill.com/docs/security-guidelines) |
| Plugin marketplace | [verified-skill.com/docs/plugins](https://verified-skill.com/docs/plugins) |
| Submit a skill for verification | [verified-skill.com/docs/submitting](https://verified-skill.com/docs/submitting) |
| FAQ | [verified-skill.com/docs/faq](https://verified-skill.com/docs/faq) |
| Browse the registry | [verified-skill.com](https://verified-skill.com) |
## Contributing
Issues and PRs welcome at [github.com/anton-abyzov/vskill](https://github.com/anton-abyzov/vskill). To submit a skill to the registry, see [verified-skill.com/docs/submitting](https://verified-skill.com/docs/submitting).
## License
MIT