Skip to content

azusachino/harus-skills / skills/toolbelt

toolbelt

Verified

Choose 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

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 ofUseFor
ls / cat / dueza / bat / dustlisting, viewing, disk usage
grep / findripgrep (rg) / fdtext/file search
grep for code structureast-grep (sg)AST-aware search & rewrite
sed (substitute)sdfind & replace
git diffdelta — already wired as the pagerdiff/log/show/blame
a noisy reflow diffdifftastic (difft)AST diff, opt-in
ps / dig / xxdprocs / doggo / hexylprocesses, DNS, hex
curl (API testing)xhHTTP requests
jq for non-JSONdaselYAML/TOML/XML/CSV query+convert
wc -l (code count)tokeicode statistics (LOC)
ad-hoc regex designgrexgenerate regular expressions
spell-check sourcetypostypo linting in code + docs
ad-hoc SQLduckdb; psql/sqlx-cli per projectdata + migrations
benchmarkinghyperfine (CLI), oha (HTTP)perf checks
python / pip / pipxuv / uvxPython runtime, deps, tools
node / npm / npxbun / bunxJS/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 with mise exec -- <tool>. Nix/Home Manager supplies the global machine environment. Honor an existing project's devShell until its toolchain is deliberately migrated.
  • make is the task runner — use the repository's own targets; run make check before commits and make validate before PRs. Verify actual hook configuration before claiming these gates run automatically.
  • JSON → jq — always jq for JSON processing; never python3 -c or inline Python. Reach for dasel the 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 (replaces python/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 (manage pyproject.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 (replaces node/npm/npx/yarn/pnpm):
    • bun run script.ts (runs TS directly, no compile step), bun test
    • bun install (fast install), bun add zod / bun remove zod
    • bunx — 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

TaskToolIdiom
Find textripgrep (rg)rg -n "pattern", rg -t rust foo, rg -l pat (files only)
Find filesfdfd -e nix, fd -t f name, fd -H (include hidden)
List direzaeza -la --git, eza --tree --level=2
View filebatbat file, bat -p (plain, no decorations for piping)
Disk usagedustdust -d 2 (depth 2)
Jump dirszoxidez 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 every console.log(...) call, any argument)
    • sg run -p 'foo($$$ARGS)' --rewrite 'bar($$$ARGS)' -l py -U (rename a call, preserving all args; -U applies in place)
    • Reach for sg over rg the 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 (no sed escaping pain):
    • sd 'foo' 'bar' file.txt (in-place, no -i needed)
    • sd -p 'foo' 'bar' file.txt (preview diff, don't write)
    • sd '(\w+)@(\w+)' '$2.$1' file (capture groups with $1)
    • Reach for sed only for stream edits in portable scripts.
    • For code-structure rewrites (rename a call, swap an API) use ast-grep --rewrite instead — 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 than curl for hand-driven requests:
    • xh get https://api.example.com/users (auto-pretty JSON)
    • xh post api.local/items name=example (JSON body from k=v)
    • xh -f post url field=val (form), xh --headers get url (headers only)
    • xh get url Authorization:"Bearer $TOK" (header with :)
    • Use curl in scripts / when exact wire control or --resolve is 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,defaultBranchRef
    • gh 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 api over raw HTTP for GitHub metadata; use --jq to 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 jq for pure-JSON pipelines (it's still the default for JSON); reach for dasel the moment the format isn't JSON. dasel handles 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 (from postgresql) — Postgres client. Not installed globally: it arrives through a project's .mise.toml (mise exec -- psql) or , psql for a one-off, so check before assuming it is on PATH.
    • 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 run
    • sqlx migrate revert, cargo sqlx prepare (offline query cache)

Debug & inspect

  • procs — modern ps:
    • procs (all), procs nginx (filter by name), procs --tree
    • procs --sortd cpu (sort by CPU desc), shows ports/TTY/user.
  • doggo — modern dig for DNS debugging:
    • doggo example.com, doggo MX example.com
    • doggo example.com @1.1.1.1 (specific resolver), --json for 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.log or cmd | 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 by programs.delta. git diff/log/show/blame render side-by-side with line numbers and n/N to jump hunks. Use git --no-pager diff for 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. delta highlights a line diff; difft changes 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.

DomainToolsReach for it when
Nix workflownh (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 extrasgit-cliff (changelog from conventional commits), gh, git-lfsgenerating a release changelog, driving GitHub, large files
Kubernetesk9s (TUI), kubectl, stern (multi-pod log tail)inspecting/driving a cluster, tailing pod logs
Cloud & syncrclonesyncing to/from cloud/object storage
Containers (Linux)podman, buildah, skopeobuilding/running/inspecting OCI images (rootless, daemonless)
Secretssops, ageencrypting/decrypting secrets in the repo
Watch & runwatchexecre-run a command on file changes (tests, builds)
Lint & formatshellcheck, shfmt, yamlfmt, prettier, markdownlint-cli2, typos, pre-commitlinting/formatting shell, YAML, JS/TS, Markdown; spell-check; hook setup
Lang toolinggolangci-lint, ruff/ty (Python), cargo-update/-sweep/-cacheproject-local linting, Rust cargo maintenance
Archives & docsouch (compress/extract), typst (doc compiler)packing/unpacking archives, typesetting
Shell & navnavi (interactive cheat sheet), fzf, zoxide, yazi (file manager)fuzzy-finding, cheat lookups, browsing files
Runtime pinningmise (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 → jq remains the default (per global CLAUDE.md).

  • For a tool command -v cannot find, comma fetches and runs any nixpkgs binary on demand. Its command name is a single comma, so it reads oddly inline:

    , ffmpeg -i in.mov out.mp4
    

    Good for a one-off; reaching for the same tool repeatedly is a signal to add it to harus-config. Fall back to the classic when comma is unavailable too.

  • command -v <tool> is the check. Tool inventories drift: scripts/tools is hand-maintained help text, packages.nix declares intent a machine may not have switched to, and this skill's own table is a third copy. Verify against the machine.

  • command -v sees binaries on PATH, and that is all. A fish function (cprune, gbs, zf) is real in an interactive shell and invisible to it; so is anything run through uvx, bunx or comma. And a package's binary can differ from its name — tailspin installs tspin. Before concluding a tool is absent, check the fish functions and the package's actual binary name.

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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall