Quickstart

This walks the full enforcement loop end to end: connect → sync → pull → gate → audit. It assumes you already have an skillsvault organisation (create one at the console) and the skillsvault CLI on your machine.

No CLI yet?

See Install & connect to build or download the single Go binary first. The rest of this page assumes skillsvault is on your PATH.

Connect this machine

The interactive flow opens your browser, signs you in, and authorizes the machine — no key to copy and paste:

skillsvault login

For CI or headless machines, connect non-interactively with an org slug and an agent key from Settings → Agent keys:

skillsvault configure --org acme --key skillsvault_ak_… --url https://skillsvault.io

Either way, the CLI fetches and pins your org's Ed25519 public key, so every bundle it later loads must be signed by your org. State lives in ~/.skillsvault/config.json.

Sync the signed policy bundle

skillsvault sync

This pulls the policy bundle, verifies its signature against the pinned key, and writes it to ~/.skillsvault/bundle.json. A bundle that fails verification is rejected and the last-good bundle is kept. You'll see something like:

✓ bundle v1750848000 verified & synced · 4 skills · 3 active policies
  → next: skillsvault pull

Install the org's approved skills

skillsvault pull --all

pull installs every approved skill into each AI harness it detects on the machine, and removes any banned skill it finds already installed — that removal is the governance action. Target a single harness with --harness claude_code, or a raw directory with --dir ./skills.

▶ claude_code  ~/.claude/skills
  ✓ acme/hubspot-crm-entry@1.3.0
  ⛔ removed banned acme/teamleader-crm-entry
  1 installed · 1 banned removed (1 banned total)

Gate a skill invocation

The gate evaluates a skill name against the local bundle and returns a decision. The exit code is the protocol: 0 allow/warn, 2 halt.

skillsvault gate --skill acme/hubspot-crm-entry   # ✓ ALLOW  (exit 0)
skillsvault gate --skill acme/teamleader-crm-entry # ⛔ HALT  (exit 2)

To enforce automatically inside Claude Code, wire the PreToolUse hook:

skillsvault install-hook   # prints the .claude/settings.json snippet

Confirm the audit trail

Every gate decision is shipped asynchronously to the control plane. Open Audit in the console (or query the API) and you'll see the allowed / warned / blocked event with the skill, version, machine, harness, and matched policy. The audit log is insert-only and immutable.

What just happened

skillsvault login      → pinned the org signing key, minted a device key
skillsvault sync       → fetched + verified the signed bundle (no skills yet)
skillsvault pull       → installed approved skills, removed banned ones
skillsvault gate       → evaluated locally: HALT on banned, ALLOW on active
                   shipped an audit event to the cloud

The cloud was on the distribution path (sync, pull) but never on the decision path (gate) — which is why a skill never waits on the network. Next, learn the full command set or how to author and publish a skill.

Verify the whole loop with the e2e suite

The repo ships a 11-scenario end-to-end test that exercises configure → sync → pull → gate → audit against a running control plane:

bash scripts/e2e.sh https://skillsvault.io

It asserts bad keys get 401, good keys 200, banned skills are excluded and removed when sideloaded, halts exit 2, the Claude Code hook emits permissionDecision: "deny", and audit events reach the cloud.