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