docs: teach token-efficient vx agent workflows

.agents/skills/vx-best-practices/SKILL.md

@@ -5,7 +5,7 @@ description: "Best practices for using vx effectively. Use when following recomm
 
 # 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, and prefer templates over custom code when creating providers.
+> **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
 
@@ -42,8 +42,8 @@ vx install node@22
 Always commit `vx.lock` to ensure reproducible builds:
 
 ```bash
-git add vx.lock
-git commit -m "chore: update dependencies"
+vx git add vx.lock
+vx git commit -m "chore: update dependencies"
 ```
 
 ### 4. Keep Agent Work Small and Observable
@@ -66,9 +66,24 @@ 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 --log | vx rg -n -m 50 "error|failed|panic"
+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
@@ -86,7 +101,7 @@ vx add just
 vx lock
 
 # 4. Commit configuration
-git add vx.toml vx.lock
+vx git add vx.toml vx.lock
 ```
 
 ### Team Onboarding

.agents/skills/vx-commands/SKILL.md

@@ -1,15 +1,19 @@
 ---
 name: vx-commands
-description: "Complete vx CLI command reference. Use when looking up specific vx command syntax, flags, or output formats. All commands support --json for structured output and --output-format toon for token-optimized output."
+description: "Complete vx CLI command reference. Use when looking up specific vx command syntax, flags, output formats, or token-efficient forwarding. vx-native commands support --json, --toon, --compact, and --output-format; forwarded tools keep native output unless compact mode is explicitly requested."
 ---
 
 # VX Command Reference
 
-> **Quick rule**: All vx commands support `--json` for structured output and `--output-format toon` for token-optimized output (saves 40-60% tokens). Set `VX_OUTPUT=json` to default all commands to JSON.
+> **Quick rule**: Prefer semantic reduction first: `--json` with selected fields, then `--jq`/`vx rg` filtering, then `--compact` for broad logs. Set `VX_OUTPUT=json`, `VX_OUTPUT=toon`, or `VX_OUTPUT=compact` only when you want that default for the whole invocation.
 
 ## Structured Output Commands (AI-Optimized)
 
-All commands support `--json` for structured output and `--output-format toon` for token-optimized output (saves 40-60% tokens).
+vx-native commands support `--json`, `--toon`, `--compact`, and
+`--output-format <text|json|toon|compact>`. Forwarded tools such as `vx git`,
+`vx gh`, `vx cargo`, or `vx npm` keep their native stdout by default; use the
+tool's own structured flags first, or add `vx --compact ...` when broad
+subprocess output must be filtered.
 
 ### Project Analysis
 
@@ -68,7 +72,7 @@ vx sync --json              # Sync from vx.toml
 ```
 
 **Output fields (install)**:
-- `runtime` - Tool name
+- `runtime` - Runtime name
 - `version` - Installed version
 - `path` - Installation path
 - `duration_ms` - Installation duration
@@ -109,6 +113,7 @@ vx list --json
 ### TOON Format (Token-Optimized)
 ```bash
 vx list --output-format toon
+vx list --toon
 # Output:
 # runtimes[50]{name,installed,description}:
 #   node,true,Node.js runtime
@@ -118,10 +123,43 @@ vx list --output-format toon
 
 TOON format is recommended for AI agents - it saves 40-60% tokens compared to JSON.
 
+### Compact Format and Forwarded Logs
+```bash
+# vx-native compact summary
+vx --compact list node
+vx list --output-format compact
+
+# Forwarded subprocess filtering
+vx --compact gh run view 789 --log
+vx --compact --filter-level aggressive cargo test
+```
+
+Compact mode is RTK-inspired: it strips ANSI noise, collapses repeated lines,
+keeps error-looking lines, and enforces a line budget for subprocess output.
+Use it after semantic options like `gh --json --jq` or `vx rg` filters.
+
+### GitHub and CI Triage
+```bash
+# Smallest useful status view
+vx gh run view 789 --json status,conclusion,jobs --jq '.jobs[] | {name,conclusion}'
+
+# Failure search with capped matches
+vx gh run view 789 --log | vx rg -n -m 80 "error|failed|panic|Traceback|FAILED|warning"
+
+# Broad fallback without raw-log token cost
+vx --compact gh run view 789 --log
+```
+
+Do not rely on default `vx gh` or `vx git` output to save tokens. Their default
+behavior is transparent forwarding; savings come from selected fields, `--jq`,
+search filters, or explicit `--compact`.
+
 ### Environment Variable
 ```bash
 export VX_OUTPUT=json       # Default to JSON output
 export VX_OUTPUT=toon       # Default to TOON output
+export VX_OUTPUT=compact    # Default to compact output/filtering
+export VX_FILTER_LEVEL=normal  # light, normal, aggressive
 ```
 
 ## Command Groups
@@ -190,7 +228,11 @@ vx cache clean              # Clean cache
 
 ```bash
 --json                      # JSON output
---output-format <text|json|toon>   # Output format
+--toon                      # TOON output
+--compact, -u               # Compact RTK-style output / subprocess filter
+--output-format <text|json|toon|compact>   # Output format
+--fields <a,b,c>            # Field mask for JSON-capable vx commands
+--filter-level <light|normal|aggressive>   # Compact subprocess filter level
 --verbose                   # Verbose output
 --debug                     # Debug output
 --use-system-path           # Use system PATH

.agents/skills/vx-troubleshooting/SKILL.md

@@ -256,6 +256,28 @@ vx --trace node --version
 vx --verbose install node
 ```
 
+### Noisy CI and Log Triage
+
+When debugging GitHub Actions, do not start by reading the full log. Use
+structured status first, then capped searches, then compact mode if the failure
+still needs broad context:
+
+```bash
+# Job status without logs
+vx gh run view <run-id> --json status,conclusion,jobs --jq '.jobs[] | {name,conclusion}'
+
+# Focused failure search
+vx gh run view <run-id> --log | vx rg -n -m 80 "error|failed|panic|Traceback|FAILED|warning"
+
+# Broad fallback with compact filtering
+vx --compact gh run view <run-id> --log
+```
+
+Interpret keyword searches carefully. Passing tests may contain names like
+`returns_failure_envelope PASSED`, and build commands may include flags such as
+`--warnings-as-errors`; confirm the job conclusion and surrounding lines before
+treating a match as the root cause.
+
 ### Cache Inspection
 
 ```bash
@@ -393,6 +415,7 @@ When a user reports a vx issue, follow this decision tree:
    → Ensure the GitHub Action is used: loonghao/vx@main
    → Add github-token for rate limit avoidance
    → Use cache: 'true' for faster CI runs
+   → Inspect logs in order: `--json --jq`, capped `vx rg`, then `vx --compact`
 
 8. General error (exit code 1)
    → Run: vx doctor for full diagnostics

.agents/skills/vx-usage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vx-usage
-description: "Teaches AI agents how to use vx, the universal dev tool manager. Use when the project has vx.toml or .vx/, or when the user mentions vx, tool version management, Git/GitHub operations, or cross-platform setup. vx auto-manages Node.js, Python, Go, Rust, and 138 tools via Starlark DSL providers. Also covers MCP integration patterns and GitHub Actions."
+description: "Teaches AI agents how to use vx, the universal dev tool manager. Use when the project has vx.toml or .vx/, or when the user mentions vx, tool version management, Git/GitHub operations, or cross-platform setup. vx auto-manages Node.js, Python, Go, Rust, and 142 providers via Starlark DSL provider.star files. Also covers MCP integration patterns and GitHub Actions."
 ---
 
 # VX - Universal Development Tool Manager
@@ -55,7 +55,7 @@ vx git commit -m "fix: example"
 vx gh issue view 123
 vx gh pr view 456 --json title,state,headRefName
 vx gh pr checks 456
-vx gh run view 789 --log
+vx gh run view 789 --json status,conclusion,jobs
 ```
 
 ### Token-Efficient Agent Workflows
@@ -82,7 +82,9 @@ vx git grep -n "CommandOutput" origin/main -- crates/vx-cli
 vx gh issue view 123 --json title,state,labels,body
 vx gh pr view 456 --json title,state,headRefName,baseRefName,files
 vx gh pr checks 456 --json name,state,conclusion,link
-vx gh run view 789 --log | vx rg -n "error|failed|panic|warning"
+vx gh run view 789 --json status,conclusion,jobs
+vx gh run view 789 --json jobs --jq '.jobs[] | {name,conclusion,startedAt,completedAt}'
+vx gh run view 789 --log | vx rg -n -m 80 "error|failed|panic|Traceback|warning"
 
 # Structured filtering
 vx jq -r '.files[].path' pr.json
@@ -92,9 +94,23 @@ vx yq '.jobs | keys' .github/workflows/ci.yml
 Token-saving defaults for agents:
 - Start with `vx rg`, `vx fd`, `vx git diff --stat`, and `vx git diff --name-only`; open full files or full diffs only after locating the relevant surface.
 - Use `vx gh --json ...` with selected fields, and add `--jq` when a small projection is enough.
-- Use vx structured output flags when the vx command supports them: `--json`, `--fields`, `--toon`, or `--output-format toon`.
+- Use vx structured output flags when the vx command supports them: `--json`, `--fields`, `--toon`, `--compact`, or `--output-format toon|compact`.
 - For forwarded runtimes like `vx node`, `vx cargo`, or `vx npm`, use that tool's own quiet, JSON, or filtering flags when available.
 - Pipe large logs through vx-managed filters such as `vx rg`, `vx jq`, or `vx yq` before reading them.
+- Use `vx --compact <tool> ...` only when you still need broad subprocess output after structured fields and grep-style filters are not enough. It preserves vx transparency unless explicitly requested.
+- Do not expect default `vx git` or `vx gh` forwarding to shrink output; explicit `--json`, `--jq`, filtering, or `--compact` is what saves tokens.
+
+Compression decision tree for CI/log triage:
+1. Status only: `vx gh run view <run> --json status,conclusion,jobs --jq '.jobs[] | {name,conclusion}'`.
+2. Suspected failure: `vx gh run view <run> --log | vx rg -n -m 80 "error|failed|panic|Traceback|FAILED|warning"`.
+3. Broad but bounded context: `vx --compact gh run view <run> --log`.
+4. Last resort: full raw logs, preferably saved to a file and searched locally before being pasted into an agent prompt.
+
+Observed on a successful 5,589-line GitHub Actions run: selected `gh --json --jq`
+projection was about 500 tokens, raw `gh --log` output was about 226k tokens,
+and `vx --compact gh --log` was about 15.9k tokens. That makes semantic
+selection the default, compact mode the fallback for broad context, and raw logs
+the exception.
 
 ### Agent Operating Principles
 
@@ -122,7 +138,9 @@ Examples:
 vx rg -n -m 20 "render_token_savings|OutputRenderer" crates/vx-cli crates/vx-metrics
 vx git diff --stat origin/main...HEAD
 vx git diff --name-only origin/main...HEAD
-vx gh run view 789 --log | vx rg -n -m 50 "error|failed|panic"
+vx gh run view 789 --json status,conclusion,jobs --jq '.jobs[] | {name,conclusion}'
+vx gh run view 789 --log | vx rg -n -m 50 "error|failed|panic|Traceback|FAILED"
+vx --compact gh run view 789 --log
 vx metrics tokens --last 20 --json
 ```
 
@@ -289,7 +307,7 @@ vx msvc@14.40 cl main.cpp
 | lib | `vx msvc lib` | Library manager |
 | nmake | `vx msvc nmake` | Make utility |
 
-## Supported Tools (138 Providers)
+## Supported Tools (142 Providers)
 
 | Category | Tools |
 |----------|-------|
@@ -318,7 +336,7 @@ vx msvc@14.40 cl main.cpp
 
 ## Provider System (Starlark DSL)
 
-All 138 providers are defined using **provider.star** (Starlark DSL) — a declarative, zero-compilation approach. Each provider lives in `crates/vx-providers/<name>/provider.star`.
+All 142 providers are defined using **provider.star** (Starlark DSL) — a declarative, zero-compilation approach. Each provider lives in `crates/vx-providers/<name>/provider.star`.
 
 vx uses a **two-phase execution model** (inspired by Buck2):
 1. **Analysis Phase (Starlark)**: `provider.star` runs as pure computation, returning descriptor dicts. No I/O.
@@ -402,7 +420,7 @@ Key modules:
 5. **Use `vx git`** instead of `git` for repository operations
 6. **Use `vx gh`** instead of `gh` for GitHub issue, PR, checks, and workflow operations
 7. **Use `vx rg`, `vx fd`, `vx jq`, and `vx yq`** for scoped search and structured filtering
-8. **Prefer token-efficient output**: `--json`, selected fields, `--jq`, `--toon`, `--output-format toon`, and narrow globs
+8. **Prefer token-efficient output**: `--json`, selected fields, `--jq`, `--toon`, `--compact`, `--output-format toon|compact`, and narrow globs
 9. **Check `vx.toml`** first to understand project tool requirements
 10. **Use `vx run <script>`** for project-defined scripts
 11. **Never suggest manual tool installation** - vx handles it automatically

AGENTS.md

@@ -487,7 +487,7 @@ Use `@main` for latest, or pin to a release tag. Full guide: [`docs/guides/githu
 
 1. **Check for `vx.toml`** → if present, always use `vx` prefix
 2. **Never suggest manual installation** — `vx` handles it
-3. **Use structured output**: `vx list --json` or `vx list --output-format toon`
+3. **Use token-efficient output**: prefer `--json` with selected fields, `--jq`, `--toon`, and explicit `--compact` for broad logs
 4. **For MCP servers**, replace `npx`/`uvx` with `vx` in config
 5. **For CI/CD**, use `loonghao/vx@main` GitHub Action
 
@@ -572,6 +572,13 @@ For a full error-by-error decision tree, see [`docs/appendix/troubleshooting.md`
 
 ```bash
 vx list --json             # JSON output
-vx list --output-format toon      # Token-optimized (saves 40-60% tokens)
+vx list --output-format toon      # Token-oriented structured output
+vx --compact gh run view 123 --log # Compact forwarded subprocess output
 vx analyze --json          # Project analysis
 ```
+
+For CI and other huge logs, use this order: `vx gh ... --json --jq` for status,
+`vx gh ... --log | vx rg -n -m 80 "error|failed|panic|Traceback"` for focused
+matches, then `vx --compact ...` when broad context is still needed. Default
+`vx git` and `vx gh` remain transparent forwarded commands; compacting is an
+explicit opt-in.