/rtk-skill

name: rtk-skill
description: Use when running shell commands that produce verbose output (git, test, build, lint, package managers, docker). Prefix with rtk to save 60-90% tokens. Terrain projects use explicit rtk prefix (no global hook).
version: 1.2.0

RTK Skill (Rust Token Killer)

[RTK](https://github.com/rtk-ai/rtk) is a CLI proxy that **filters and compresses command output** before it reaches the LLM (typically **60–90% token savings**).

Resolve the RTK command (read first)

Use **conventional paths only** — never machine-specific absolute paths like `/Users/...` or `C:\Users\...`.

On Windows, tools deploy to `%USERPROFILE%\.terrain\bin\` (also written as `~/.terrain/bin/` in Git Bash / PowerShell 7+). Binaries use `.exe` extensions; PATHEXT resolves `rtk` → `rtk.exe`.

| Priority | Command prefix | When | |----------|----------------|------| | 1 | `~/.terrain/bin/rtk` | Terrain env integration or desktop app (see existence check below) | | 2 | `bunx @terrain-ai/rtk` | No Terrain install; needs network once | | 3 | `npx @terrain-ai/rtk` | Same as bunx if Bun unavailable |

Optional manifest (local, gitignored): `.terrain/env/agent-tools.json` — same `~/.terrain/bin/…` conventions.

**Existence check (cross-platform):**

| Shell | Check | |-------|-------| | bash / zsh / Git Bash | `[ -x ~/.terrain/bin/rtk ] \|\| [ -x ~/.terrain/bin/rtk.exe ]` | | PowerShell | `Test-Path "$HOME\.terrain\bin\rtk.exe"` | | cmd | `if exist "%USERPROFILE%\.terrain\bin\rtk.exe"` |

**Shell rules:**

• Invoke as `~/.terrain/bin/rtk <cmd>` — tilde expands at word start in bash/zsh/Git Bash/PowerShell 7+.
• Do **not** `export RTK="$(jq -r .rtk …)"` then `"$RTK"` — quoted variables do not expand `~`.
• Do **not** assume bare `rtk` is on PATH.

Example (pick one prefix per session after the existence check):

# bash / Git Bash
if [ -x ~/.terrain/bin/rtk ] || [ -x ~/.terrain/bin/rtk.exe ]; then
  PREFIX=~/.terrain/bin/rtk
else
  PREFIX="bunx @terrain-ai/rtk"
fi
$PREFIX git status

# PowerShell
$PREFIX = if (Test-Path "$HOME\.terrain\bin\rtk.exe") { "$HOME\.terrain\bin\rtk.exe" } else { "bunx @terrain-ai/rtk" }
& $PREFIX git status

Verify:

~/.terrain/bin/rtk gain || bunx @terrain-ai/rtk gain

We do **not** run `rtk init` / global hooks.

Golden rule

> For **any shell command** that prints more than a few lines, run it as **`<rtk-prefix> <cmd>`** instead of bare `<cmd>`.

Applies to: git, tests, builds, linters, package managers, docker/kubectl, `ls`/`grep`/`find`, `gh`, etc.

In examples below, `<rtk>` means your resolved prefix (`~/.terrain/bin/rtk` or `bunx @terrain-ai/rtk`).

Critical: built-in Read / Grep / Glob

Claude Code, Cursor, and similar agents often have **native Read/Grep tools that bypass Bash hooks**.

Those tools **do not** auto-rewrite to RTK. For token-efficient file/search workflows, use:

| Instead of native tool | Use | |------------------------|-----| | Read large source file | `<rtk> read path/to/file.rs` | | Read signatures only | `<rtk> read path/to/file.rs -l aggressive` | | Grep / search repo | `<rtk> grep "pattern" .` or `<rtk> rg "pattern"` | | Find files | `<rtk> find "*.ts" .` | | List directory | `<rtk> ls .` |

**Exception:** `.terrain/agent/context.md` and short `knowledge/*.md` — read directly (already dense).

Command reference (by category)

Git (high savings)

<rtk> git status
<rtk> git log -n 20 --oneline
<rtk> git diff
<rtk> git diff --staged
<rtk> add -A && <rtk> git commit -m "msg"
<rtk> git push
<rtk> git pull

Tests (failures-focused, ~90% savings)

<rtk> cargo test
<rtk> test cargo test
<rtk> bun test
<rtk> vitest
<rtk> jest
<rtk> pytest
<rtk> go test

Build & lint

<rtk> cargo build
<rtk> cargo clippy
<rtk> tsc
<rtk> eslint .
<rtk> ruff check
<rtk> next build

Package managers

<rtk> pnpm list
<rtk> bun install
<rtk> pip list

Files & search

<rtk> ls src/
<rtk> read src/lib/foo.rs
<rtk> read src/lib/foo.rs -l aggressive
<rtk> grep "fn handle_" .
<rtk> find "*.svelte" .
<rtk> diff file1 file2

Containers / cloud (when used)

<rtk> docker ps
<rtk> docker logs <container>
<rtk> kubectl get pods
<rtk> gh pr list

Errors only

<rtk> err npm run build

Global flags

<rtk> -u git status
<rtk> -v cargo test

When command fails

RTK may collapse output but preserves **exit codes**. On failure, look for a tee path in output:

FAILED: 2/15 tests
[full output: ~/.local/share/rtk/tee/....log]

Read that log if you need the full unfiltered output — do not blindly re-run the same verbose command.

Bypass RTK (rare)

RTK_DISABLED=1 git status

When NOT to use RTK

| Use RTK | Use other Terrain skills instead | |---------|----------------------------------| | Shell command output | Architecture → `terrain-knowledge-skill` / `context.md` | | git test build lint | Symbol relations → `codegraph-skill` | | `<rtk> read` for code slices | Structured repomix index → `repomix-context-skill` |

**Workflow order:** Terrain knowledge → codegraph → repomix slices → **rtk** for remaining shell work.

Analytics (optional)

<rtk> gain
<rtk> gain --history
<rtk> discover

Do not

• Run `rtk init` or `rtk init -g` — Terrain owns agent guidance via AGENTS.md
• Assume hooks rewrite commands — **you** must type the rtk prefix
• Re-run identical verbose commands after RTK already summarized them
• Use wrong rtk package (verify with `<rtk> gain`)

Complements

• **terrain-knowledge-skill** — what project knowledge to read first
• **codegraph-skill** — AST/call-graph queries
• **repomix-context-skill** — grep repomix pack for source sections