The skilvault client

The client puts your SkilVault skills into Claude Code, Codex, Grok and AGY, and gives you and your agent the commands to work with your library.

How your CLI uses it

Each skill you select shows up in your CLI as an ordinary skill, under its own name, in one skills folder per CLI: ~/.claude/skills for Claude Code, ~/.agents/skills for Codex, ~/.grok/skills for Grok and ~/.gemini/config/skills for AGY (its desktop app, CLI and IDE). What sits there is a small lazy skill: the skill's name, its signed description, and one line that loads the skill itself through skilvault read at the moment your CLI uses it. So your CLI picks the right skill by itself, and what it follows is always the current, signature-checked version, with your notes and your account's licence line.

• Using one takes one extra step: the lazy skill tells the agent to run skilvault read, which is pre-approved, and follow what it prints.
• AGY checks a command it has not seen before running it, so the first use of a vault skill may ask you to approve a look at the skilvault program; skilvault read itself is pre-approved.
• Answer by name: when you say “use the commit-lint skill” or “what skills do I have?” the agent runs read or list.
• Find the rest: on every prompt, SkilVault names the skills from the whole catalog that fit it (route, below), and the skilvault skill tells the agent to run find when nothing it has fits.

If you name a skill that is not pinned, the agent runs read anyway on Pro and Unlimited. On the free plan, naming a skill outside your pinned library gets you told so, not a guess at its content.

Running it yourself

The client lives at ~/.local/bin/skilvault. If that directory is on your PATH the command is skilvault. Otherwise call it by full path, or add an alias (this page writes skilvault for short):

alias skilvault="$HOME/.local/bin/skilvault"

Errors are printed to standard error and start with skilvault:; the command exits non-zero, so it works in scripts.

setup

skilvault setup is what the installer runs: it puts the skilvault skill into each CLI it finds, runs sync, and runs hooks install. Run it again after installing another CLI.

sync

skilvault sync writes a lazy skill for each skill you selected into each CLI's skills folder, and removes the ones you no longer have. It checks every skill's signature first, and a skill that fails keeps whatever was there before. It only ever changes what SkilVault put there: your own skills and links are never touched, even when they share a name with a SkilVault skill. Full copies left by older versions of the client are moved to ~/.local/share/skilvault/retired/ rather than deleted, in case you edited one.

You rarely need to run it: every session start runs it in the background, at most every 30 minutes. Codex and AGY list only so many skills; when your library is bigger, sync gives them as many as fit and says how many are left for search.

$ skilvault sync
claude: 12 skill(s) in /Users/you/.claude/skills
codex: 9 skill(s) in /Users/you/.agents/skills (3 more than the listing budget holds: reach them with search)

update

skilvault update is the same as sync, kept for scripts written for older clients.

list

Shows every skill your key can use: name, version and a short description.

$ skilvault list
commit-lint   1.0.0   Conventional-commit checks, PR title hygiene, and changelog generation…
research      1.0.0   Investigate a question against high-trust primary sources…

find

skilvault find <a few words about the task> matches your words against the whole published catalog on your machine, with the local model (meaning) and keywords, and prints the five closest skills. Your words are not sent anywhere: sync keeps a copy of the catalog (names and descriptions in catalog.json; each skill's description vector and its example requests' vectors in catalog.vec) next to the cache, and after the first download fetches only what changed. When nothing fits closely it says so, and only then sends your words to the server, which records them as a skill people want. Before the first sync, the server's search answers instead. skilvault search is the same command.

$ skilvault find review a pull request
code-review   1.0.0   [pinned]    Review the changes since a fixed point along two axes…
commit-lint   1.0.0   [readable]  Conventional-commit checks, PR title hygiene…

It also uses what you learned: a skill whose notes mean the same as your words moves up and shows the note, and skills you actually read after being suggested rank a little higher next time. That is kept on your machine only. [pinned] skills are always listed in your CLIs. [readable] means your plan reads it anyway (Pro and Unlimited): read fetches and verifies it on demand. [pin to use] means your plan reads only pinned skills: pin it in the dashboard first (Choosing your skills). When the server's search answers instead, a [not selected] tag means the same as [pin to use] on the free plan.

read

skilvault read <name> checks the skill's signature, downloads it (once per version), checks its checksum, and prints its SKILL.md, then your notes for it. This is what every lazy skill runs. Each use is recorded (see usage).

If the skill bundles other files, such as scripts or reference notes, read also unpacks it into the client's cache and prints that folder and the file list above the SKILL.md, so the agent can run the scripts from there.

$ skilvault read commit-lint
---
name: commit-lint
description: Conventional-commit checks…
---
# commit-lint
…

usage

read records each use of a skill: the skill, its version, which CLI used it and when. Never your code, prompts or file paths. The client sends these to SkilVault in the background so you can see which skills you actually use on the Usage page, unless you turn off Report which skills you use on the Install page. skilvault usage show lists the uses not sent yet; skilvault usage flush sends them now.

doctor

skilvault doctor shows, for each CLI, how many vault skills it lists, whether its skilvault skill is there, which skills in its folder are not from SkilVault, and anything in the way: a CLI that would see a skill twice, read not being pre-approved, a setting that forbids skilvault commands. skilvault doctor --live also asks Codex and Grok what they list. It reads folders and settings only, calls no model and sends nothing.

route

A hook that Claude Code and Codex run when you send a prompt (Grok runs Claude's hooks but throws away what a prompt hook says, so it gets nothing from it): it names up to three skills from the whole catalog that fit the prompt and that the CLI doesn't already list, by name (and, for pinned skills, their signed description), so the agent can read one. It matches on this machine only, with the local model and the catalog copy: your prompt is never sent anywhere or stored. Skills your plan can't read are never named. Turn it off with Suggest vault skills from your prompts on the Install page. You do not run it yourself. In Grok and AGY the agents use find instead.

learn

SkilVault learns on your machine which suggestions you actually use. When find or the prompt hook suggests a skill and you read it within 30 minutes, that skill ranks a little higher next time, and the way you asked (as a vector, never the words) becomes your own example for it, so similar requests find it again. At most 20 examples per skill and 500 in all are kept, oldest first out. None of it leaves your machine. skilvault learn show lists what was learned; skilvault learn clear forgets it (your notes are kept).

suggest

skilvault suggest lists vault skills that fit the project you are in. It reads the project's dependency files (package.json, pyproject.toml, go.mod, Cargo.toml, Dockerfile, compose files and similar), turns them into stack keywords such as nextjs or stripe, and asks SkilVault which skills match.Only those keywords are sent, never your code or file contents, and only while Suggest skills for my projects is on (Install page). Results are cached per project and refreshed when the dependencies change or once a day.

$ skilvault suggest
SkilVault skills that fit this project (from its stack: typescript, docker, nextjs):
- docker-troubleshooting: Guides systematic diagnosis of failing Docker containers… (matches: docker)
Read one with `skilvault read <name>` when the work calls for it; ignore the rest.

Keywords that no skill matches are passed to SkilVault's administrators as requests for new skills. They go through the same review as any other request, and nothing is published without a person checking it.

hooks

skilvault hooks install sets up Claude Code, Codex and Grok: when a session starts they sync in the background and run suggest, and again after an edit to a dependency file; Codex also runs route for each prompt. It pre-approves skilvault read, so vault skills load without a prompt (for Codex, also outside its sandbox, which read needs for the network). Grok runs Claude Code's hooks too, so when both are installed Grok gets no second copy. setup runs it for you. skilvault hooks remove takes everything out again and leaves your other hooks and rules untouched. Codex asks you to approve new hooks once: run /hooks in Codex. Hooks an older client added to Gemini CLI, which is no longer supported, are removed.

defaults

Some skills ask which options to use each time they run (the audit skill asks for its scope and depth, for example). skilvault defaults saves your usual answers on this machine only, so the skill uses them instead of asking. Anything you type when you run the skill still wins.

$ skilvault defaults set audit --bugs --quick
saved defaults for 'audit': --bugs --quick
$ skilvault defaults show audit
--bugs --quick
$ skilvault defaults clear audit

Only options the skill itself declares can be saved, one per either/or choice. Options that let an agent act without asking you — such as --auto, --loop or --merge — are never saved: you choose those each time. SkilVault never sees or sets these defaults.

note

skilvault note <skill> "<what was learned>" records one lesson from using a skill, next to it and never inside it, so the signed skill is untouched. Inside a project it applies to that project only; skilvault note global <skill> <id> makes it apply everywhere. A lesson seen once is a learning; when it comes up again, skilvault note promote <skill> <id> makes it a rule. A note is one line, and anything that looks like a key or password is refused. Your agent does this itself when a skill asks it to. If you turned on Help improve skills with what my agent learns, a rule is also sent to SkilVault when it is promoted (or with skilvault note share <skill> <id>): one sentence, with project names, paths and email addresses removed first. Once enough people learn the same thing it can become part of the skill, and your copy of the rule then retires on its own.

notes

skilvault notes <skill> shows the rules and learnings for a skill (they are also shown after the skill whenever it is read).skilvault notes history <skill> lists earlier versions, skilvault notes undo <skill> steps back one change, and skilvault notes clear <skill> removes them (undo brings them back). Project notes live in .skilvault/notes/ in the project, global ones next to your config.

recall

skilvault recall <what you are about to do> lists the skills in your library that fit the task and the lessons learned on similar work, matched by meaning rather than exact words. It needs the local memory (below).

memory

The local model is part of every install: setup installs it and sync puts it back if it goes missing (it needs Node.js 18 or newer; about 25 MB to download, once). It matches your requests against the catalog for find and route, and keeps one file next to your config with everything learned while using skills: a new note that means the same as an earlier one is pointed out, and recall works. Every file it downloads must match a fingerprint built into the client, and the signed skills themselves are never stored in it. skilvault memory status shows what it holds; skilvault memory install installs it again. Until it is installed, find falls back to keywords and the server's search, and notes are kept as plain files; skilvault doctor reports it as a problem.

signer

For the operator only. skilvault signer setup --key-file <path> (or --agent-pub <key.pub> --sock <socket>) records which signing key to use, and skilvault signer start runs a small signer on 127.0.0.1 that answers only your SkilVault site. When the bulk import wizard signs a batch, the signer checks every skill itself and shows them on its own page, where you enter the key's passphrase. The site only ever receives the signature. skilvault signer install (macOS) makes it start at every login, so there is nothing to start by hand; skilvault signer uninstall undoes that. skilvault signer status says whether it is running. Everyone else can ignore this command.

Configuration

The client reads ~/.config/skilvault/config, a plain shell-style file:

SV_HOST="https://your-skilvault-host"
SV_KEY="svk_live_…"

Requirements

bash, curl, python3, unzip, shasum and column. All are present on macOS and mainstream Linux distributions. The client keeps your manifest for 10 minutes and each skill version once, by checksum. When SkilVault cannot be reached it keeps working from the last manifest for up to 24 hours; after that, or as soon as SkilVault refuses your key, skills stop loading until it can check again.