Local skill operations

Design, vendor, and install agent skills from one CLI.

`vd` keeps a skills repository reproducible: upstream sources live in `skills.toml`, resolved commits live in `skills.lock`, and local agent targets are generated from the same tree.

Read the workflow Install into Codex

Install

Install `vd` as a single binary, then run it from any directory inside a Git repository. For local development in this repository, run the command through Go so you exercise the current source tree.

# install the latest release
go install github.com/vanducng/skills/tools/vd/cmd/vd@latest

# or run from this repository
cd tools/vd
mise exec -- go run ./cmd/vd --root /Users/vanducng/skills --version

Root resolution

Every command needs a repository root. `vd` resolves it in a predictable order: first the `--root` flag, then the `VD_ROOT` environment variable, then a walk upward from the current directory until it finds `.git/`.

Operational note Use `--root` in scripts and CI. It prevents accidental writes to the wrong checkout when commands are launched from nested directories or editor tasks.

Core workflow

The normal path starts with a manifest, adds one or more upstream skills, vendors them into `skills/`, and then builds local targets. `vd sync` runs `vd build` automatically unless you pass `--no-build`.

$ vd init
$ vd add browserbase/skills/browser --as browser
$ vd sync
$ vd build

# result
skills/browser/
skills.lock
.claude-plugin/marketplace.json
.agents/skills/browser -> ../../skills/browser

Command matrix

Most teams use a small subset daily and keep the rest for maintenance work. The command surface is intentionally scriptable: diagnostics go to stderr, generated output is stable, and destructive operations require explicit flags when local edits are detected.

Task	Command	When to use it
Track	`vd add`	Register an upstream skill source in `skills.toml`.
Vendor	`vd sync`	Fetch tracked or pinned skills and update `skills.lock`.
Review	`vd list`, `vd doctor`	Inspect lock state and local drift before changing files.
Freeze	`vd pin`	Lock a skill to a known commit SHA for reproducible installs.
Install	`vd install`	Write Codex symlinks or install the Claude Code plugin bundle.

Codex install

Codex is the default local install target. `vd install codex` symlinks every local skill into `$HOME/.agents/skills`, which keeps installed skills live as the repository changes. Use `--copy` only when you need a frozen snapshot.

vd install codex
vd install codex research plan
vd install codex --scope repo
vd install codex --copy --force

Claude plugin

The Claude path builds `.claude-plugin/marketplace.json` and `plugin.json`, registers this repository as a local marketplace, and installs the configured plugin. Use `--dry-run` before changing a teammate's machine or a CI image.

vd install claude --dry-run
vd install claude --scope user

Install picker

Run `vd install` without an agent to open the terminal picker. It exposes four choices: Codex user symlinks, Codex repo symlinks, Codex user copies, and Claude Code plugin installation. Scripted workflows should pass the agent name directly.

Tracked skills `tracked` follows upstream HEAD on `vd update`. Use this for public skills you want to keep current.

Pinned or detached `pinned` freezes a SHA. `detached` keeps files on disk and stops all upstream sync behavior.

Drift checks `vd doctor` reports modified, missing, and untracked skill directories without changing files.

Cache reset `vd cache clean` removes `.vd-cache/`; the next add or sync repopulates it from upstream.

Safe updates

Before pulling upstream changes, inspect local drift and compare individual skills. `vd sync` and `vd update` refuse to overwrite locally modified skills unless `--force` is passed, so the safer path is to review first and detach any skill that has become local source material.

vd doctor
vd diff research
vd update research

Environment

`VD_ROOT` pins a default repository root, `VD_NO_UPDATE_CHECK=1` disables release checks, and `XDG_CACHE_HOME` changes where update metadata is stored. In CI, update checks are automatically disabled.