Vx Best Practices

Best practices for using vx effectively. Use when following recommended patterns for tool management, project setup, and team workflows with vx.

Security Scan

This is an instruction-only 'best practices' guide for using the vx tool; its requirements and instructions are consistent with that purpose and it does not request credentials or install code.

Purpose & Capability

The skill name and description match the SKILL.md content: guidance for vx usage, project setup, CI, and team workflows. There are no unrelated environment variables, binaries, or config paths requested that would be out of scope for a documentation-style skill.

Instruction Scope

The instructions are confined to vx-related workflows (vx.toml, vx.lock, vx commands, git, CI config). They do recommend using a GitHub Action (loonghao/vx@main) and run commands like git commit and vx install — appropriate for a how-to doc but these are operational commands users should review before executing. Minor supply-chain note: the example action references the 'main' branch of a third-party repo rather than a pinned release, which is a recommended hardening step.

Install Mechanism

There is no install specification and no code files — the skill is instruction-only and does not download or write code to disk.

Credentials

The SKILL.md mentions environment variables as examples (e.g., API_KEY, DATABASE_URL) but the skill does not request or require any credentials or secrets. No disproportionate or unrelated credential access is requested.

Persistence & Privilege

The skill is not marked always:true and does not request persistent presence or modify other skills or system-wide settings. Autonomous invocation is allowed (platform default) but not combined with other red flags.

Assessment

This skill is a documentation-only guide for vx and appears internally consistent. Before acting on any suggested commands: (1) review and understand commands like 'vx install', 'git commit', and 'vx setup' — don't run them blindly; (2) verify the third-party GitHub Action example (loonghao/vx@main) and prefer pinning to a specific release or commit to reduce supply-chain risk; (3) never paste real secrets into example files shown here — follow your usual secrets management practices; and (4) if you don't use vx in your projects, this skill is not needed. If you want a deeper check, provide the source of the referenced vx tooling or your repository so I can flag any risky commands or unpinned external dependencies.

Golden rule: Always prefix tool commands with vx in vx-managed projects. Use vx.toml for project-level tool versions, commit vx.lock for reproducibility, and prefer templates over custom code when creating providers.

General Principles

1. Always Use vx Prefix

In vx-managed projects, always prefix tool commands with vx:

# ✅ Correct
vx npm install
vx cargo build
vx just test

# ❌ Wrong (might use system tools)
npm install
cargo build
just test

2. Prefer Project-Level Configuration

Use vx.toml to ensure consistency across team members:

# ✅ Correct - defined in vx.toml
vx sync

# ❌ Wrong - manual installation
vx install node@22

3. Commit Lock Files

Always commit vx.lock to ensure reproducible builds:

git add vx.lock
git commit -m "chore: update dependencies"

Project Setup

Initial Setup

# 1. Initialize project
vx init

# 2. Add required tools
vx add node@22
vx add go
vx add just

# 3. Generate lock file
vx lock

# 4. Commit configuration
git add vx.toml vx.lock

Team Onboarding

New team members only need to run:

# Clone repository
git clone <repo>
cd <repo>

# One command setup
vx setup

CI/CD Configuration

Use the vx GitHub Action:

# .github/workflows/ci.yml
- uses: loonghao/vx@main
  with:
    setup: 'true'
    cache: 'true'

Version Management

Version Selection Strategy

Scenario	Constraint	Example
Development	Major version	node = "22"
CI/CD	Exact version	node = "22.0.0"
Library	Range	node = ">=18 <23"
Latest features	"latest"	uv = "latest"

Avoid Over-Specification

# ✅ Good - flexible for patch updates
[tools]
node = "22"
go = "1.22"

# ❌ Bad - too rigid for development
[tools]
node = "22.0.0"    # Blocks security patches
go = "1.22.0"      # Requires update for each patch

LTS for Production

# Use LTS versions for stability
[tools]
node = "lts"        # Auto-updates to latest LTS

Scripts Organization

Naming Conventions

[scripts]
# Standard scripts (run with: vx run <name>)
dev = "npm run dev"
test = "npm run test"
build = "npm run build"
lint = "npm run lint"

# Colon-separated variants (run with: vx run test:watch)
test:watch = "npm run test -- --watch"
test:coverage = "npm run test -- --coverage"
build:prod = "npm run build -- --mode production"

# CI-specific scripts
ci = "just ci"
ci:test = "cargo test --all-features"

Script Dependencies

# Scripts can depend on specific tools
[scripts]
lint = "eslint . && cargo clippy"  # Uses node and rust
build = "go build ./..."           # Uses go

Environment Variables

Project-Level Defaults

[env]
NODE_ENV = "development"
DEBUG = "app:*"

# Required variables (vx will warn if missing)
API_KEY = { env = "API_KEY", required = true }

# Default values
PORT = { default = "3000" }

Secrets Management

Never commit secrets. Use environment variables:

# .env (add to .gitignore)
DATABASE_URL=postgresql://...
API_KEY=secret123

# Reference in vx.toml
[env]
DATABASE_URL = { env = "DATABASE_URL" }

Performance Optimization

Cache Configuration

[cache]
# Enable aggressive caching
enabled = true
ttl = 86400  # 24 hours

# Cache location
dir = "~/.vx/cache"

Pre-install Common Tools

# In project setup, pre-install tools
vx sync --parallel

Use Offline Mode

# When network is unreliable
vx sync --offline

Cross-Platform Considerations

Platform-Specific Tools

[tools]
# Cross-platform tools first
node = "22"
uv = "latest"

# Platform-specific
[tools.msvc]
version = "14.42"
os = ["windows"]

[tools.brew]
version = "latest"
os = ["macos", "linux"]

Cross-Platform Scripts

# Use tools that work everywhere
[scripts]
build = "just build"     # just is cross-platform
test = "cargo test"      # cargo is cross-platform

# Avoid platform-specific commands
# ❌ build = "make build"  # Unix only

Security Best Practices

Verify Checksums

vx automatically verifies checksums. For additional security:

# Verify installation
vx install node@22 --verify

Minimal Permissions

# Install as regular user, not root
# ❌ sudo vx install node

# vx manages user-level installations
vx install node

Audit Dependencies

# Audit installed tools
vx audit

# Check for vulnerabilities
vx npm audit

Team Workflows

Adding New Tools

# 1. Add to vx.toml
vx add python@3.12

# 2. Update lock file
vx lock

# 3. Commit changes
git add vx.toml vx.lock
git commit -m "feat: add python 3.12"

Updating Tools

# 1. Check for updates
vx outdated

# 2. Update specific tool
vx update node

# 3. Update all tools
vx update --all

# 4. Commit lock file changes
git add vx.lock

Removing Tools

# 1. Remove from vx.toml
vx remove tool-name

# 2. Clean up installation
vx sync --clean

# 3. Commit changes
git add vx.toml vx.lock

Monitoring & Maintenance

Regular Checks

# Weekly: Check for updates
vx outdated

# Monthly: Clean cache
vx cache clean

# After issues: Run diagnostics
vx doctor

Health Check Script

[scripts]
doctor = "vx doctor"
check = "vx check"
audit = "vx npm audit && cargo audit"

Anti-Patterns to Avoid

1. Manual Tool Installation

# ❌ Don't manually install tools in vx projects
npm install -g node  # Conflicts with vx

# ✅ Let vx manage tools
vx npm install

2. Ignoring Lock Files

# ❌ Don't ignore vx.lock
git rm --cached vx.lock

# ✅ Always commit lock files
git add vx.lock

3. Global vx.toml

# ❌ Don't rely on global configuration
~/.vx/vx.toml

# ✅ Use project-level configuration
./vx.toml

4. Hardcoded Paths

# ❌ Don't hardcode absolute paths
[env]
TOOL_PATH = "/Users/alice/.vx/tools/node"

# ✅ Use vx variables
[env]
TOOL_PATH = "${VX_ROOT}/tools/node"

Migration Guide

From nvm/fnm → vx

# 1. Export current versions
node --version > .nvmrc

# 2. Create vx.toml
vx init

# 3. Add node version
vx add node@$(cat .nvmrc | tr -d 'v')

# 4. Remove nvm
rm -rf ~/.nvm

From pyenv → vx

# 1. Check current Python version
python --version

# 2. Create vx.toml
vx init

# 3. Add uv (recommended Python manager)
vx add uv

# 4. Remove pyenv
rm -rf ~/.pyenv

Provider Development Best Practices

Choose the Right Template

Decision tree for new providers:

• Tool releases on GitHub with Rust target triple? → github_rust_provider (most common)
• Tool releases on GitHub with Go goreleaser? → github_go_provider
• Single binary download (no archive)? → github_binary_provider
• System package manager only? → system_provider
• Custom download source? → Hand-write download_url function

For most tools, use a template instead of writing custom functions:

# ✅ Good — Use template (10 lines)
_p = github_rust_provider("owner", "tool",
    asset = "tool-{vversion}-{triple}.{ext}")

# ❌ Avoid — Custom download_url when template works
def download_url(ctx, version):
    # 30+ lines of custom code...

Understanding the ctx Object

All provider.star functions receive a ctx object:

Field	Example value	Description
ctx.platform.os	"windows", "macos", "linux"	Current OS
ctx.platform.arch	"x64", "arm64"	CPU architecture
ctx.install_dir	~/.vx/store/node/22.0.0	Install path
ctx.store_dir	~/.vx/store	Global store root
ctx.cache_dir	~/.vx/cache	Cache directory

Provider Naming

# ✅ Correct terminology
name = "ripgrep"              # Provider name
runtimes = [runtime_def("rg")]  # Runtime name (what user types)

# Common pattern: provider name = project name, runtime name = binary name
# ripgrep provider → rg runtime
# rust provider → cargo, rustc, rustup runtimes

Platform Constraints

Return None from download_url for unsupported platforms:

def download_url(ctx, version):
    platform = platform_map(ctx, _PLATFORMS)
    if not platform:
        return None  # Not supported on this platform
    return "https://example.com/v{}/tool-{}.tar.gz".format(version, platform)

Bundled Runtimes

Use bundled_runtime_def for tools shipped inside another:

runtimes = [
    runtime_def("node"),                     # Primary runtime
    bundled_runtime_def("npm", "node"),       # npm comes with node
    bundled_runtime_def("npx", "node"),       # npx comes with node
]

vx Development Best Practices

Quick Development Cycle

vx just quick                    # format → lint → test → build
vx cargo check -p vx-cli         # Fast type-checking for one crate
vx cargo test -p vx-starlark     # Test one crate

Code Organization Rules

1. Layer dependencies go downward only — Never import from higher layers
2. Tests in tests/ directories — Never inline #[cfg(test)]
3. Use rstest for parameterized tests
4. Use tracing for logging, never println! or eprintln!
5. Use correct terminology — Runtime, Provider, provider.star

AI Agent Documentation Ecosystem

vx maintains a comprehensive set of AI agent configuration files for 15+ agents:

File	Purpose	Audience
AGENTS.md	Primary AI agent entry point — rules, architecture, quick reference	All AI coding agents (official standard)
CLAUDE.md	Claude Code specific instructions with @-import support	Claude Code
llms.txt	Concise LLM-friendly project index (llmstxt.org protocol)	LLMs discovering the project
llms-full.txt	Detailed LLM documentation with full examples	LLMs needing deep context
.github/copilot-instructions.md	GitHub Copilot-specific instructions	GitHub Copilot
.cursor/rules/*.mdc	Modern Cursor IDE rules with YAML frontmatter (4 files)	Cursor AI (new format)
.cursorrules	Cursor IDE agent rules (legacy format, still supported)	Cursor AI (legacy)
.clinerules	Cline/Roo agent rules	Cline
.windsurfrules	Windsurf AI IDE rules	Windsurf
.kiro/steering/*.md	Kiro AI IDE steering documents	Kiro
.trae/rules/*.md	Trae AI IDE project rules	Trae
skills/	Distributable skill files for 15+ AI agents	ClawHub, vx ai setup

Best practice: When making changes that affect AI agent behavior (terminology, architecture, commands), update AGENTS.md first — it is the single source of truth. Other files derive from it.