vd-cli — Gerenciador de Skills para Agentes de Código
vanducng/vd-cli
Sync, lock e distribua skills de código para múltiplos agentes com um comando
Ver no GitHubSingle-binary vendoring package manager que centraliza e sincroniza skills reutilizáveis para agentes de código como Claude Code e OpenAI Codex. Substitui copy-paste manual entre repositórios por um manifesto único (skills.toml) que garante versionamento SHA-locked e geração determinística de configurações específicas para cada agente.
Instalação
npx convez-ai vanducng/vd-cli1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Manter skills sincronizados entre Claude Code, Codex e futuros agentes
- Evitar drift de configuração entre diferentes layouts de agente
- Versionamento e pinning de skills com SHA para reprodutibilidade
Veredito

Ferramenta bem arquitetada para quem orquestra múltiplos agentes de código em paralelo. Resolve um problema real de sincronização, mas tem curva de aprendizado inicial e utilidade máxima em stacks com 2+ agentes ativos.
README
A tradução para o português deste README ainda está na fila.
Supported agents
vd builds a vendor-locked skills tree once and emits the manifest each agent stack expects. Today that's:
| Agent | Status | What vd build emits |
|---|---|---|
| Claude Code | ✅ first-class | .claude-plugin/marketplace.json + plugin.json (bundle or per-skill mode) |
| OpenAI Codex | ✅ first-class | .agents/skills/<name> repo-scope symlinks; vd install codex for user scope |
More targets land as the coding-agent ecosystem grows — the emitter interface (internal/target/iface.go) is intentionally small so adding a new agent is a single file.
Why vd-cli
You're already running two or three coding agents. They all want skills but each wants a different layout, a different manifest, a different install path. So you copy-paste between repos, lose track of what came from where, and your agents drift out of sync with their upstreams.
vd-cli flips this:
- One manifest —
skills.tomlis the source of truth for which skills, from where, pinned at what SHA. - One sync —
vd syncfetches atomically, detects local edits before overwriting, populates a deterministic cache. - One build —
vd buildregenerates every agent's manifest byte-for-byte from the lock. No drift between Claude's marketplace.json and Codex's symlinks. - No vendor lock-in — your skills are normal directories on disk. Delete vd-cli and they still work.
Install
Install script (macOS/Linux):
curl -fsSL https://raw.githubusercontent.com/vanducng/vd-cli/main/install.sh | sh
Installs to ~/.local/bin (override with VD_INSTALL_DIR, pin with VD_VERSION). Later upgrades: vd upgrade.
Homebrew:
brew install vanducng/tap/vd
Homebrew 5.x requires trusting third-party taps first: brew trust vanducng/tap.
go install:
go install github.com/vanducng/vd-cli/v2/cmd/vd@latest
Pre-built binaries: see releases for darwin/linux/windows × amd64/arm64.
Windows release archives are zip files. In PowerShell:
$version = "v2.1.0"
$asset = "vd_windows_x86_64.zip"
Invoke-WebRequest "https://github.com/vanducng/vd-cli/releases/download/$version/$asset" -OutFile $asset
Expand-Archive $asset -DestinationPath ".\vd" -Force
.\vd\vd.exe --version
Use vd_windows_arm64.zip on Windows ARM64.
From source:
git clone https://github.com/vanducng/vd-cli.git
cd vd-cli
make build && mv vd /usr/local/bin/vd
Quick start
# 1. Bootstrap a manifest at the repo root
vd init
# 2. Track an upstream skill
vd add browserbase/skills/browser --as browser
# 3. Vendor it locally (fetches, hashes, locks)
vd sync
# 4. Emit manifests for every configured agent
vd build
# 5. (Optional) install local skills into Codex user scope
vd install codex
After these five commands:
skills/browser/— the vendored skill source, ready to edit..claude-plugin/marketplace.json+plugin.json— Claude Code picks it up automatically..agents/skills/browser— Codex repo-scope symlink resolves toskills/browser/.skills.lock— pinned commit SHA, content hash, every byte deterministic.
Commands
| Command | Description |
|---|---|
vd init | Create skills.toml at the repo root |
vd add <source>/<path> | Register an upstream skill |
vd list | Print tracked skills as a table |
vd sync [skill...] | Vendor tracked/pinned skills; runs vd build |
vd update [skill...] | Bump tracked skills to upstream HEAD |
vd diff <skill> | Diff upstream cache vs local skills/<name>/ |
vd doctor | Report drift between skills.lock and skills/ |
vd pin <skill> <sha> | Lock a skill to a specific commit SHA |
vd detach <skill> | Stop tracking; leave files on disk |
vd remove <skill> | Remove from manifest, lock, and (default) disk |
vd build [target...] | Emit manifests + symlinks for each agent target |
vd install [agent] [skill...] | Install local skills into Codex or Claude Code user scope |
vd cache clean | Delete the .vd-cache/ download cache |
Run vd <command> --help on any verb for flags, examples, and exit codes.
Global flags
| Flag | Short | Description |
|---|---|---|
--quiet | -q | Suppress non-error output |
--verbose | -v | Verbose output (reserved) |
--root | Override repo root path | |
--version | Print vd <version> |
Repo root resolution: --root flag → VD_ROOT env → walk up from CWD to the first .git/. Both --root and VD_ROOT are validated and error out on invalid values.
Environment
| Var | Effect |
|---|---|
VD_ROOT | Pin a default repo root |
VD_NO_UPDATE_CHECK | Disable the upstream version check |
XDG_CACHE_HOME | Override the cache directory (default ~/.cache) |
CI | When set, the version check is auto-disabled |
Version check
vd-cli checks GitHub for new releases at most once per 24 hours and prints a one-line nudge to stderr when a newer version exists:
vd 2.0.0 (latest: 2.0.1). Upgrade: brew upgrade vd
The check runs in the background and is silent on any failure. Disabled automatically for dev builds, when CI is set, and when stderr is not a terminal. Set VD_NO_UPDATE_CHECK=1 to opt out explicitly.
Documentation
- Usage guide — core workflows and common commands
- Command reference — flags, examples, exit codes
- Config schema — every
skills.tomlfield - FAQ — naming, conflicts, dirty-refuse, design decisions
- Migration guide — from copy-paste, subtree, or submodules
- Contributing — dev setup, release flow, commit style
- Changelog — version history
License
MIT © Duc Nguyen