vx-best-practices

Files (1)

• SKILL.md

SKILL.md (first lines)

# VX Best Practices

> **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, prefer templates over custom code when creating providers, and prefer structured or compact output before reading large logs.

## General Principles

### 1. Always Use `vx` Prefix

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

```bash
# ✅ 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:

```bash
# ✅ 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:

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

### 4. Keep Agent Work Small and Observable

When an AI agent uses vx, optimize for correctness, speed, judgment, and token
efficiency:

- Read enough surrounding code to understand the local pattern, then stop exploring.
- Prefer targeted searches, focused file sections, scoped diffs, selected JSON fields, and capped logs.
- Make the smallest maintainable change that solves the request.
- Reuse existing project helpers before creating new abstractions.
- Avoid single-use wrappers, speculative architecture, and unrelated cleanup.
- Validate according to risk: focused tests for narrow changes, broader checks for shared behavior.
- Preserve evidence from the actual command, CI job, or runtime surface when debugging.

For large or unknown output, scope first and filter through vx-managed tools:

```bash
vx rg -n -m 20 "SearchTerm" src
vx git diff --stat
vx git diff --name-only origin/main...HEAD
vx gh pr view 123 --json title,state,files
vx gh run view 456 --json status,conclusion,jobs --jq '.jobs[] | {name,conclusion}'
vx gh run view 456 --log | vx rg -n -m 50 "error|failed|panic|Traceback|FAILED"
vx --compact gh run view 456 --log
```

Use this priority order for token-heavy surfaces:
1. Ask for semantic data: `--json`, selected fields, `--jq`, `--fields`, `--toon`.
2. Search the raw source with caps: `vx rg -n -m 80 ...`, `vx jq`, `vx yq`.
3. Use `vx --compact <tool> ...` for broad subprocess output that still needs context.
4. Read full raw output only after the smaller views fail to explain the issue.

The compact filter follows RTK-style principles: preserve high-signal lines,
strip presentation noise, collapse repetition, cap volume, and measure savings
with `vx metrics tokens --json` when comparing approaches. Do not make
transparent forwarding commands (`vx git`, `vx gh`, `vx cargo`, `vx npm`) compact
by default; agents should opt in explicitly with `--compact` so scripts and
humans keep the native tool contract.

## Project Setup

### Initial Setup

```bash
# 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
vx git add vx.toml vx.lock
```

### Team Onboarding

New team members only need to run:

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

# One command setup
vx setup
```

### CI/CD Configuration

Use the vx GitHub Action:

```yaml

From dcc-mcp/dcc-mcp-3dsmax, MIT.

More from dcc-mcp/dcc-mcp-3dsmax