convez.ai
SkillAutomaçãoIntermediário
vanducng

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 GitHub
InicialPluginScore · de 0 a 100

Single-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-cli

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 2 semanas
Versão
v3.14.3
Issues abertas
4
Contribuidores
3

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.

Release Go Reference License: MIT CI


Supported agents

vd builds a vendor-locked skills tree once and emits the manifest each agent stack expects. Today that's:

AgentStatusWhat 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.toml is the source of truth for which skills, from where, pinned at what SHA.
  • One sync — vd sync fetches atomically, detects local edits before overwriting, populates a deterministic cache.
  • One build — vd build regenerates 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 to skills/browser/.
  • skills.lock — pinned commit SHA, content hash, every byte deterministic.

Commands

CommandDescription
vd initCreate skills.toml at the repo root
vd add <source>/<path>Register an upstream skill
vd listPrint 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 doctorReport 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 cleanDelete the .vd-cache/ download cache

Run vd <command> --help on any verb for flags, examples, and exit codes.

Global flags

FlagShortDescription
--quiet-qSuppress non-error output
--verbose-vVerbose output (reserved)
--rootOverride repo root path
--versionPrint 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

VarEffect
VD_ROOTPin a default repo root
VD_NO_UPDATE_CHECKDisable the upstream version check
XDG_CACHE_HOMEOverride the cache directory (default ~/.cache)
CIWhen 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

License

MIT © Duc Nguyen

Ver o original no GitHub

Bom para

Relacionados