azusachino/harus-skills / skills/toolbelt
toolbelt
VerifiedChoose haru's preferred CLI tools for terminal search, inspection, HTTP, structured data, and benchmarking when tool selection or usage guidance is needed.
Toolbelt Skill
Prefer these tools for interactive terminal work. Check availability on the current machine; repository tooling and the host agent's editing rules take precedence over these defaults.
Table of Contents
- Resolve uncertainty
- Substitution table (always-on)
- Tooling discipline (carried from global defaults)
- Runtimes & package managers
- Search & navigate
- Edit text
- HTTP / API debugging
- GitHub and GitLab
- Data & SQL
- Debug & inspect
- Benchmark
- Domain & infra tools (know these exist)
- When NOT to substitute
Rule of thumb: classic tools for piping inside scripts that must be portable; modern tools for interactive/agent work where clarity and ergonomics win.
Resolve uncertainty
Use command -v, the installed tool's --help, and repository configuration to resolve missing tools or unfamiliar flags. Continue with a supported fallback when it preserves the requested result. Ask when the remaining uncertainty changes scope, risks user data, or requires authority the user has not supplied. A recipe here is not permission to install tools, load-test a service, or mutate remote state.
Substitution table (always-on)
Reach for the right-hand tool by default; fall back to the classic only when the modern one is absent.
| Instead of | Use | For |
|---|---|---|
ls / cat / du | eza / bat / dust | listing, viewing, disk usage |
grep / find | ripgrep (rg) / fd | text/file search |
grep for code structure | ast-grep (sg) | AST-aware search & rewrite |
sed (substitute) | sd | find & replace |
git diff | delta — already wired as the pager | diff/log/show/blame |
| a noisy reflow diff | difftastic (difft) | AST diff, opt-in |
ps / dig / xxd | procs / doggo / hexyl | processes, DNS, hex |
curl (API testing) | xh | HTTP requests |
jq for non-JSON | dasel | YAML/TOML/XML/CSV query+convert |
wc -l (code count) | tokei | code statistics (LOC) |
| ad-hoc regex design | grex | generate regular expressions |
| spell-check source | typos | typo linting in code + docs |
| ad-hoc SQL | duckdb; psql/sqlx-cli per project | data + migrations |
| benchmarking | hyperfine (CLI), oha (HTTP) | perf checks |
python / pip / pipx | uv / uvx | Python runtime, deps, tools |
node / npm / npx | bun / bunx | JS/TS runtime, deps, tools |
Tooling discipline (carried from global defaults)
Use these defaults when the project does not specify its own tooling:
- Mise for project tools — pin tools and runtimes in
.mise.toml, and run them withmise exec -- <tool>. Nix/Home Manager supplies the global machine environment. Honor an existing project's devShell until its toolchain is deliberately migrated. makeis the task runner — use the repository's own targets; runmake checkbefore commits andmake validatebefore PRs. Verify actual hook configuration before claiming these gates run automatically.- JSON →
jq— alwaysjqfor JSON processing; neverpython3 -cor inline Python. Reach fordaselthe moment the format isn't JSON.
Runtimes & package managers
Use the project's declared runtime and lockfile. For ad-hoc work, prefer uv and bun when compatible.
uv— Python runtime + dependency + project manager (replacespython/pip/venv/pipx/poetry):uv run script.py(auto-resolves deps),uv run pytest(run a tool in the project env)uv add httpx/uv remove httpx(managepyproject.toml),uv sync(install lockfile)uv venv(create env),uv pip install -r req.txt(pip-compatible shim)uvx— run a Python CLI tool one-off without installing:uvx ruff check,uvx ruff@0.6 format.
bun— JS/TS runtime + package manager + bundler (replacesnode/npm/npx/yarn/pnpm):bun run script.ts(runs TS directly, no compile step),bun testbun install(fast install),bun add zod/bun remove zodbunx— execute a package, downloading it if needed:bunx prettier --check config.json,bunx tsx file.ts.
Caveats: preserve the project's package manager, interpreter, and CI contract; changing runners can change compatibility or lockfiles. For one-off commands, inspect the installed version's help before using version-sensitive flags.
Search & navigate
| Task | Tool | Idiom |
|---|---|---|
| Find text | ripgrep (rg) | rg -n "pattern", rg -t rust foo, rg -l pat (files only) |
| Find files | fd | fd -e nix, fd -t f name, fd -H (include hidden) |
| List dir | eza | eza -la --git, eza --tree --level=2 |
| View file | bat | bat file, bat -p (plain, no decorations for piping) |
| Disk usage | dust | dust -d 2 (depth 2) |
| Jump dirs | zoxide | z proj after visiting once |
Prefer rg/fd over grep -r/find — faster, respects .gitignore, sane defaults. When piping bat output, add -p to strip line numbers/borders.
ast-grep(sg) — structural, syntax-aware code search & rewrite (matches by AST, not regex — immune to formatting/whitespace):sg run -p 'console.log($A)' -l ts(find everyconsole.log(...)call, any argument)sg run -p 'foo($$$ARGS)' --rewrite 'bar($$$ARGS)' -l py -U(rename a call, preserving all args;-Uapplies in place)- Reach for
sgoverrgthe moment the pattern is about code shape (a call, an import, a JSX element) rather than literal text — no brittle regex, no false hits inside strings/comments.
Edit text
sd— find & replace, literal-friendly, real regex (nosedescaping pain):sd 'foo' 'bar' file.txt(in-place, no-ineeded)sd -p 'foo' 'bar' file.txt(preview diff, don't write)sd '(\w+)@(\w+)' '$2.$1' file(capture groups with$1)- Reach for
sedonly for stream edits in portable scripts. - For code-structure rewrites (rename a call, swap an API) use
ast-grep --rewriteinstead — it edits by AST, not text, so formatting and string/comment matches can't trip it up.
HTTP / API debugging
xh— httpie-style client, faster thancurlfor hand-driven requests:xh get https://api.example.com/users(auto-pretty JSON)xh post api.local/items name=example(JSON body fromk=v)xh -f post url field=val(form),xh --headers get url(headers only)xh get url Authorization:"Bearer $TOK"(header with:)- Use
curlin scripts / when exact wire control or--resolveis needed.
oha— load testing:oha -n 1000 -c 50 https://api.local/health.
GitHub and GitLab
gh— GitHub-native repository, PR, release, and workflow operations:gh repo view OWNER/REPO --json nameWithOwner,defaultBranchRefgh api repos/OWNER/REPO/releases/tags/v1.2.3 --jq '{name,body,html_url}'gh pr create --fill,gh pr view,gh run view- Prefer
gh apiover raw HTTP for GitHub metadata; use--jqto keep responses focused.
glab— GitLab-native equivalent for projects, merge requests, releases, and pipelines:glab mr create --fill,glab mr view,glab pipeline view
Use the provider-native CLI when the task targets GitHub or GitLab state. Keep xh for generic HTTP APIs and curl for scripts requiring exact wire control.
Data & SQL
dasel— one tool to query/convert JSON/YAML/TOML/XML/CSV:dasel -f config.yaml '.services.web.port'dasel -f data.json -r json -w yaml(convert JSON→YAML)dasel put -f config.yaml -v 8080 '.services.web.port'(edit YAML/TOML/etc. in place)- Use
jqfor pure-JSON pipelines (it's still the default for JSON); reach fordaselthe moment the format isn't JSON.daselhandles YAML query and edit — it's the one tool for non-JSON structured data here.
tokei— count lines of code quickly:tokei .(recursive code statistics by language)
duckdb— fast analytical SQL over files, no server:duckdb -c "select * from 'data.csv' limit 5"duckdb -c "select count(*) from read_parquet('*.parquet')"
miller(mlr) — CSV/TSV/JSON record processing:mlr --csv cut -f a,b then sort -nr b data.csv
psql(frompostgresql) — Postgres client. Not installed globally: it arrives through a project's.mise.toml(mise exec -- psql) or, psqlfor a one-off, so check before assuming it is onPATH.psql "$DATABASE_URL" -c '\dt',psql -h host -U user db
sqlx-cli— Rust SQL toolkit / migrations:sqlx database create,sqlx migrate add <name>,sqlx migrate runsqlx migrate revert,cargo sqlx prepare(offline query cache)
Debug & inspect
procs— modernps:procs(all),procs nginx(filter by name),procs --treeprocs --sortd cpu(sort by CPU desc), shows ports/TTY/user.
doggo— moderndigfor DNS debugging:doggo example.com,doggo MX example.comdoggo example.com @1.1.1.1(specific resolver),--jsonfor parsing.
hexyl— colored hex viewer:hexyl file.bin,hexyl -n 64 file(first 64 bytes), inspect encodings/headers.
tailspin(tspin) — auto-highlight logs:tspin app.logorcmd | tspin.btop— interactive system monitor.grex— generate regular expressions from user-provided test cases:grex a b c(returns^[a-c]$)grex -d -w -p email@example.com(generate with digits, words, non-space)
typos— fast source-code spell checker (skips code identifiers sensibly):typos(check the tree),typos -w(auto-fix),typos path/to/file- Good as a pre-commit gate and before shipping docs; low false-positive rate.
delta— the git pager, wired in byprograms.delta.git diff/log/show/blamerender side-by-side with line numbers andn/Nto jump hunks. Usegit --no-pager difffor raw unified text to parse, or in a narrow terminal.difftastic(difft) — the opt-in structural diff: compares ASTs, so reflow is not a change.deltahighlights a line diff;difftchanges what counts as a difference.difft old.rs new.rs(standalone), or for one command:GIT_EXTERNAL_DIFF=difft git diff- Reach for it only when a plain diff is noisy because indentation or wrapping moved but the code didn't.
Terminal multiplexing: tmux.
Benchmark
hyperfine— CLI command benchmarking with stats:hyperfine 'rg foo' 'grep -r foo .'(compare),--warmup 3.
oha— HTTP load (see above).
Domain & infra tools (know these exist)
Candidates for specialized work. Availability varies by machine; check the executable and the project's own targets before choosing one.
| Domain | Tools | Reach for it when |
|---|---|---|
| Nix workflow | nh (ergonomic nix/home-manager wrapper), nom (nix-output-monitor), nix-tree (closure explorer), nix-locate (which package owns a binary), comma (invoked as a lone , — runs a binary without installing it) | rebuilding a config, watching a build, asking why something is in the closure, finding or borrowing a missing tool |
| Git extras | git-cliff (changelog from conventional commits), gh, git-lfs | generating a release changelog, driving GitHub, large files |
| Kubernetes | k9s (TUI), kubectl, stern (multi-pod log tail) | inspecting/driving a cluster, tailing pod logs |
| Cloud & sync | rclone | syncing to/from cloud/object storage |
| Containers (Linux) | podman, buildah, skopeo | building/running/inspecting OCI images (rootless, daemonless) |
| Secrets | sops, age | encrypting/decrypting secrets in the repo |
| Watch & run | watchexec | re-run a command on file changes (tests, builds) |
| Lint & format | shellcheck, shfmt, yamlfmt, prettier, markdownlint-cli2, typos, pre-commit | linting/formatting shell, YAML, JS/TS, Markdown; spell-check; hook setup |
| Lang tooling | golangci-lint, ruff/ty (Python), cargo-update/-sweep/-cache | project-local linting, Rust cargo maintenance |
| Archives & docs | ouch (compress/extract), typst (doc compiler) | packing/unpacking archives, typesetting |
| Shell & nav | navi (interactive cheat sheet), fzf, zoxide, yazi (file manager) | fuzzy-finding, cheat lookups, browsing files |
| Runtime pinning | mise (per-project versions via .mise.toml, run with mise x -- <tool>), rustup (Rust toolchains) | a project pins a language version; switching Rust toolchains |
For tools outside this list, prefer an existing dependency or native capability. Install only within the task's authorization and the project's tool-management convention.
When NOT to substitute
-
Portable shell scripts that may run on minimal/other machines → stick to POSIX (
grep,sed,find,curl) so they don't depend on this toolbelt. -
Pure-JSON pipelines →
jqremains the default (per global CLAUDE.md). -
For a tool
command -vcannot find,commafetches and runs any nixpkgs binary on demand. Its command name is a single comma, so it reads oddly inline:, ffmpeg -i in.mov out.mp4Good for a one-off; reaching for the same tool repeatedly is a signal to add it to
harus-config. Fall back to the classic whencommais unavailable too. -
command -v <tool>is the check. Tool inventories drift:scripts/toolsis hand-maintained help text,packages.nixdeclares intent a machine may not have switched to, and this skill's own table is a third copy. Verify against the machine. -
command -vsees binaries onPATH, and that is all. A fish function (cprune,gbs,zf) is real in an interactive shell and invisible to it; so is anything run throughuvx,bunxorcomma. And a package's binary can differ from its name —tailspininstallstspin. Before concluding a tool is absent, check the fish functions and the package's actual binary name.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |