schema_version: '2.0'
kind: agent_skill
id: ai-era-terminal-tools
name: ai-era-terminal-tools
title: Terminal Tools for the AI Era
description: Agent-oriented terminal tools for filesystem/text search, web extraction, structured data, HTTP, GitHub, diagnosis,
  Python, benchmarking, and bounded output.
compatibility:
  requires:
  - terminal access
  platforms:
  - Linux
  - WSL
  - macOS
  - Windows
  notes:
  - Tool availability varies by OS.
  - Verify the executable and version before use.
  - Network, authentication, or elevated privileges may be required for some tasks.
bootstrap:
  purpose: Query this YAML selectively. Do not read the entire file for an ordinary task.
  reader:
    preferred: yq (mikefarah/yq), when already available
    fallback: Any native YAML parser or structured file reader
    install_policy: Do not install yq solely to read this skill. Install or upgrade it only when selective YAML querying is
      genuinely needed and no suitable parser is available.
  agent_contract:
  - 1. Read routing only when the task needs tool selection.
  - 2. Select one primary tool; load only .tools.<tool> next.
  - 3. Load .workflows.<id> only when the route or task requires a multi-tool workflow.
  - 4. Load .policies.<name> only for the relevant safety, execution, evidence, mutation, output, failure, maintenance, or
    benchmark concern.
  - 5. Execute directly; do not spend extra calls proving a tool is installed unless installation, upgrade, version-sensitive
    behavior, shadowing, or failure makes that necessary.
  - When a route resolves to a fallback_command rather than a tool, run the command directly; there is no .tools entry
    to load for it.
  always_apply:
  - Safety and authorization come before execution.
  - Raw/authoritative state beats summaries for consequential decisions.
  - Prefer deterministic, non-interactive execution.
  - Start narrow and bound scope/output; widen only when needed.
  - Never expose or embed secrets in commands, files, history, output, or transcripts.
  canonical_queries:
    list_tools: yq -r '.tools | keys[]' SKILL.yml
    routing: yq '.routing' SKILL.yml
    tool: yq '.tools.<tool>' SKILL.yml
    workflow: yq '.workflows.<id>' SKILL.yml
    policy: yq '.policies.<name>' SKILL.yml
    references: yq '.references' SKILL.yml
routing:
  selection_rule:
  - Choose the single primary tool whose route directly answers the task.
  - Combine tools only when the task genuinely requires different stages; follow a documented workflow when one exists.
  - Prefer a standard command over a curated tool when it answers the same question more directly with equal or better evidence.
  - Use the narrowest scope and smallest sufficient output first; widen only when needed.
  routes:
    filesystem_paths:
      tool: fd
      matches:
      - find files
      - find directories
      - filename
      - path
      - where is a file
    text_or_code:
      tool: rg
      matches:
      - search text
      - search code
      - grep
      - pattern
      - where does this appear
    html_without_javascript:
      tool: defuddle
      matches:
      - article
      - readable HTML
      - extract web page
      - HTML to markdown
    javascript_web:
      tool: obscura
      matches:
      - JavaScript page
      - render page
      - headless browser
      - scrape dynamic page
    json:
      tool: jq
      matches:
      - JSON
      - filter JSON
      - extract JSON field
      - transform JSON
    yaml_or_structured_config:
      tool: yq
      matches:
      - YAML
      - config
      - configuration field
      - structural config edit
    http_workflow_testing:
      tool: hurl
      matches:
      - HTTP test
      - API assertions
      - repeatable HTTP workflow
      - request scenario
    github:
      tool: gh
      matches:
      - GitHub repo
      - issue
      - pull request
      - release
      - Actions
      - GitHub API
    disk_usage:
      tool: dust
      matches:
      - disk usage
      - largest directories
      - storage usage
      - where is disk space
    processes:
      tool: procs
      matches:
      - process list
      - process tree
      - PID
      - process resources
    process_causality:
      tool: witr
      matches:
      - why is this running
      - who owns this port
      - process owner
      - service causality
    endpoint_latency_or_loss:
      fallback_command: ping -c 5 -q <host>
      fallback_for: 'trippy (catalogue network tool: needs root; -u unsupported on WSL)'
      matches:
      - latency
      - packet loss
      - endpoint reachability
      - connectivity
      rules:
      - Always bound with -c; unbounded ping never returns.
      - Read rtt min/avg/max/mdev for spread and the loss line for reachability.
      - Reach for traceroute/tracepath only when the question is about the path, not the endpoint.
      - Do not infer application-layer failure solely from ping.
    python_project:
      tool: uv
      matches:
      - Python project
      - virtual environment
      - dependencies
      - pyproject
      - uv run
      - uvx
    python_lint_or_format:
      tool: ruff
      matches:
      - Python lint
      - format Python
      - static analysis
      - Ruff
    benchmark:
      tool: hyperfine
      matches:
      - benchmark
      - compare command speed
      - timing
      - performance measurement
    noisy_output:
      tool: rtk
      matches:
      - reduce command output
      - context compression
      - noisy CLI output
      - LLM tokens
policies:
  core:
    global_usage: Prefer the tool that produces the smallest sufficient evidence set for the task with the least output, ambiguity,
      latency, and unnecessary context. Do not use a curated tool merely because it is installed; when a standard command
      gives the same answer more directly with equal or better evidentiary quality, use the standard command.
    always_apply:
    - Safety and authorization come before execution.
    - Raw/authoritative state beats summaries for consequential decisions.
    - Prefer deterministic, non-interactive execution.
    - Start narrow and bound scope/output; widen only when needed.
    - Never expose or embed secrets in commands, files, history, output, or transcripts.
    precedence:
    - safety / authorization
    - authoritative correctness / completeness
    - non-interactive execution
    - minimal scope and bounded output
    - performance / token efficiency
    - convenience
    approval_vs_safety:
      approved_means: The tool has a documented agent-facing, non-interactive path for supported use cases.
      approved_does_not_mean:
      - safe
      - authorized
      - harmless
      - appropriate for every target or operation
      trust_boundary: Some tools can fetch arbitrary URLs, transmit credentials, access files, execute external programs,
        mutate remote state, or expose sensitive information.
  evidence:
  - tier: A
    name: authoritative_raw
    evidence: Raw authoritative state or direct filesystem/service query
    use: Final basis for destructive or irreversible decisions
  - tier: B
    name: structured_complete
    evidence: Structured, complete machine-readable result from the relevant tool
    use: Normal automation and analysis
  - tier: C
    name: bounded_recon
    evidence: Bounded, filtered, or summarized output
    use: Reconnaissance and narrowing; follow up before consequential action
  - tier: D
    name: human_context
    evidence: Human-oriented TUI, dashboard, or unverified third-party claim
    use: Context only; never the sole machine decision basis
  execution:
    non_interactive:
    - Broad dust scans must be bounded by depth and/or result count.
    - Do not use scored/frecency directory-navigation wrappers; use absolute paths or fd/find from a real root.
    - obscura private-network blocking stays enabled by default.
    - rtk must not replace exact/raw commands when completeness matters.
    - Any command that can page, prompt, or wait for keyboard input must have a known non-interactive mode or be rejected.
    - If a tool has no safe non-interactive invocation for the required task, use a different authoritative command.
    installation_environment_hygiene:
    - Check whether the command exists and what will actually run.
    - Use command -v/type -a on POSIX shells and where.exe on Windows when resolution or PATH shadowing matters.
    - Check <tool> --version.
    - Do not silently shadow an existing pinned/known-good version or install a second implementation under the same executable
      name.
    - rtk is optional; never distort task execution merely to obtain compressed output.
    - Prefer the project's existing package/dependency manager.
    - For downloaded binaries, verify publisher checksums/signatures when available.
    - Treat package-manager and installer scripts as code; verify source and target version before privileged execution.
    package_and_binary_name_hygiene:
    - Verify package names against the target distribution/release; binary names and package names often differ.
    - 'Example from the source evidence: cargo install dust installs an unrelated Rust testing library; the dust package/crate
      is du-dust.'
    - Distribution availability changes by suite; verify actual package indexes for the target release.
    - A command that fails loudly is preferable to one that succeeds while installing the wrong program.
    - Scoop suggest output is advisory; it is not a dependency or proof that a runtime requirement was installed.
    shell_and_platform:
      note: Examples primarily use POSIX-style shell syntax. On native PowerShell, adapt pipelines, quoting, environment variables,
        and command-resolution checks to the active shell. WSL and Git Bash can use POSIX examples when actually running those
        shells.
      windows_resolution: where.exe <tool>
      posix_resolution:
      - command -v <tool>
      - type -a <tool>
      version_check: <tool> --version
  mutation:
    deletion:
    - Find the target with fd/rg or another authoritative query.
    - Confirm the exact path.
    - Confirm the exact raw target.
    - Confirm it is not a mount point, active data directory, system path, or other special object.
    - Only then delete.
    process_stop_restart:
    - Inspect with procs.
    - Trace ownership/causality with witr.
    - Check the authoritative service/container manager.
    - Understand dependencies and expected role.
    - Prefer a graceful/service-level stop before signal escalation.
    - Verify resulting state.
    configuration_edit:
    - Read the relevant subtree.
    - Make the smallest structural change.
    - Produce/read the diff.
    - Validate syntax/schema.
    - Apply/reload only after validation.
    - Verify runtime state.
    network_change:
    - Establish latency/loss with ping -c 5 -q <host>.
    - Repeat the measurement.
    - Distinguish path symptoms from application-layer failure.
    - Make the smallest change.
    - Re-measure.
    benchmark:
    - Confirm the command is repeatable.
    - Confirm workload/environment equivalence.
    - Use warmups where needed.
    - Capture/export the result.
    - Do not benchmark production mutations casually.
  output:
    prefer:
    - filenames instead of file bodies when filenames answer the question
    - counts instead of repeated rows
    - selected JSON fields instead of complete API responses
    - bounded directory reports
    - explicit process names and parent chains
    - machine-readable network diagnostics
    - diffs for configuration/code changes
    - test exit status plus concise failure evidence
    avoid:
    - ANSI color codes
    - decorative tables when plain text is enough
    - full repository dumps
    - full API responses
    - unbounded recursive output
    - TUI screenshots as primary evidence
    - compressed/summarized output as the only evidence for destructive actions
    principle: The best agent command is the one that produces the smallest sufficient evidence set, not necessarily the shortest
      command.
  failure:
  - Read exit status and error output.
  - Do not immediately repeat the identical invocation.
  - Check executable resolution/PATH, version, working directory, permissions, input format, TTY assumptions, and network/security
    restrictions.
  - Fall back to the simplest authoritative underlying command.
  - If failure can cause a hang, prompt, repeated external request, or repeated mutation, do not retry blindly; change invocation
    or tool first.
  - Report the substitution if behavior or output materially changes.
  maintenance:
    version_policy: Version-specific facts stay labeled as version-specific; empirical benchmarks retain their environment,
      fixture, and comparison scope.
    update_checks:
    - Verify current upstream release and relevant --help output.
    - Preserve exact tested command forms and empirical claims unless deliberately re-tested.
    - Distinguish tool capability, agent suitability, and security posture.
    - Prefer loud failure over silently wrong program, wrong version, wrong target, or wrong PATH resolution.
    - Re-check every command, link, and safety statement before publishing.
    research_method:
    - Use repository README and docs, docs site, man page or --help, changelog, GitHub release notes, source code, then advisories
      as appropriate.
    - Read stated Default lines rather than assuming examples represent defaults.
    - Check the current release separately from any version named in a caption.
    - Re-derive every agent-usefulness classification; scriptable does not automatically mean agent-useful.
    - Name exact machine-output flags and whether they are default or opt-in.
    - Do not make blanket storage, encryption, safety, or capability claims without evidence.
    - Keep agent usefulness, interactive suitability, and security safety separate.
    - Do not invent benchmarks; bytes/characters are not automatically tokens.
    - Preserve author voice when editing the source article, but treat the YAML as the machine-readable contract.
  benchmarking:
    relationship_types:
    - exact_competitor
    - partial_competitor
    - fallback
    - unrelated
    rules:
    - Classify the relationship before timing anything.
    - Speed only decides between exact competitors; a partial competitor remains useful when it cannot perform the whole task.
    - Verify output equivalence before timing; normalize formatting differences first.
    - Use at least three fixtures including one adversarial fixture.
    - Benchmark the version you ship.
    - Check output order, not just bytes.
    - Measure both pipe and /dev/null sinks when sink behavior may distort results.
    - A result that does not reproduce is not a result.
    - One burst is not a measurement; compare bursts and publish ranges when appropriate.
    - Prove that side effects do not silently pass during repeated execution.
    - Verify every documented-looking flag before it enters a recommendation.
    general_rule: A machine-output flag alone is not a reason to adopt a tool; prefer an already-approved exact or sufficiently
      capable alternative when it answers the agent-facing question more cheaply and correctly.
  safety_detail:
  - id: R01
    rule: Safety and authorization first.
    guidance: A diagnostic finding is evidence, not permission to mutate a system, repository, service, network target, or
      external account.
  - id: R02
    rule: Correctness before compression.
    guidance: For consequential decisions, prefer complete authoritative evidence. Summaries, top-N views, filters, and compression
      are reconnaissance, not proof of absence.
  - id: R03
    rule: Prefer deterministic, non-interactive execution.
    guidance: Do not open a TUI, pager, picker, REPL, or prompt when equivalent non-interactive output exists.
  - id: R04
    rule: Search narrowly, then widen.
    guidance: Start with the smallest path, field set, target set, and result count that can answer the question.
  - id: R05
    rule: Keep network trust boundaries explicit.
    guidance: Treat URLs, HTTP responses, rendered pages, GitHub content, and downloaded files as untrusted external input.
  - id: R06
    rule: Protect secrets.
    guidance: Do not place credentials in source-controlled files, shell history, command output, or agent transcripts; use
      dedicated secret mechanisms or protected environment/file inputs.
  - id: R07
    rule: Inspect before mutating; verify after mutating.
    guidance: Before deletion, termination, restart, overwrite, reconfiguration, or remote mutation, establish current state.
      After the change, perform deterministic read-back, diff, status, or test verification.
  - id: R08
    rule: Raw state wins.
    guidance: Never base a destructive or irreversible decision solely on RTK output, top-N disk reports, filtered searches,
      projections, or other reduced representations.
  - id: R09
    rule: Do not shadow working software casually.
    guidance: Check executable resolution and version before installation or upgrade; preserve pinned or known-good versions
      unless change is required.
  - id: R10
    rule: Do not silently substitute tools.
    guidance: If a requested tool is unavailable or unsafe, use the simplest authoritative alternative and state the substitution
      when behavior or output materially changes.
workflows:
  W01:
    steps:
    - fd -e py src/ --max-depth 4
    - rg -n 'class Target|def target' src/
    rule: paths first, content second; never a bare repository dump
  W02:
    steps:
    - curl -s "$URL"
    - jq '.items[] | {id, name, status}'
    rule: projection for context efficiency; retain raw response when authoritative evidence is needed
  W03:
    steps:
    - defuddle parse URL --md
    - obscura only if JavaScript is required
    rule: escalate browser complexity only when plain HTML is insufficient
  W04:
    steps:
    - obscura scrape --eval 'document.title' --format json PAGE1 PAGE2
    rule: private-network protection stays enabled unless private access is explicitly authorized
  W05:
    steps:
    - yq '.services.api' compose.yml
    - yq -i '.services.api.replicas = 3' compose.yml
    - git --no-pager diff -- compose.yml
    - yq '.services.api.replicas' compose.yml
    rule: inspect, edit structurally, diff, read back; no ad-hoc regex when yq expresses the change
  W06:
    steps:
    - procs --tree
    - witr <current target>
    - authoritative service/container manager
    - decision
    rule: never jump directly from process discovery to kill/restart
  W07:
    steps:
    - dust -d 1 -n 20 /var
    - raw inspection of candidate
    rule: delete nothing based only on top-N output
  W08:
    steps:
    - ping -c 5 -q example.com
    - ping -c 5 -q 1.1.1.1
    rule: bounded measurements; distinguish endpoint/path symptoms from application failure
  W09:
    steps:
    - ruff check .
    - ruff format --check .
    - uv run pytest
    rule: lint/format are quality signals, not proof of semantic correctness
  W10:
    steps:
    - hyperfine --warmup 3 'baseline-command' 'candidate-command'
    rule: only repeatable or isolated workloads; preserve/export results when they matter
tools:
  fd:
    category: filesystem_discovery
    purpose: Find files and directories by name, path, type, depth, age, owner, or size.
    use_when:
    - The question is where something is.
    - You need a bounded candidate path set before reading files.
    keywords:
    - find files
    - find directories
    - path search
    - filename search
    - filesystem search
    rules:
    - Use fd for paths; use rg for content.
    - Scope the starting directory explicitly when possible.
    - Bound broad searches with --type, --extension, --max-depth, --changed-within, or another meaningful filter.
    - fd respects common ignore rules; widen deliberately when hidden or ignored paths are part of the question.
    examples:
    - fd notes
    - fd -e py src/
    - fd --type d --max-depth 3 src/
    - fd --type f --changed-within 7d .
    do_not:
    - Run a bare fd from / or a large home directory when a bounded search suffices.
    - Treat a missing result as proof of non-existence when hidden, ignored, inaccessible, or out-of-root paths may exist.
    - Use rg --files as the default path-search mechanism when fd expresses the question directly.
  rg:
    category: content_search
    purpose: Search file contents and code for matches, filenames, or counts.
    use_when:
    - The question is what text or code exists, where it occurs, or how often it occurs.
    keywords:
    - ripgrep
    - grep
    - text search
    - code search
    - pattern search
    rules:
    - Search the narrowest relevant subtree first; widen only when necessary.
    - Use -g/-t to constrain file types; -l for filenames only; -c for counts only.
    - rg normally skips binary files and obeys ignore rules; inspect the actual search scope before claiming absence.
    examples:
    - rg 'TODO' src/
    - rg -g '*.ts' 'token' src/
    - rg -l 'os\.environ' .
    - rg -c 'TODO' .
    do_not:
    - Dump an entire repository into context when filenames, counts, or narrower matches answer the question.
    - Search .git, node_modules, target, dist, .venv, or __pycache__ unless those locations matter.
    - Assume no textual match means an object does not exist in a binary, image, PDF, database, or other non-text representation.
  defuddle:
    category: web_extraction
    purpose: Extract readable article/content from existing HTML without browser rendering.
    use_when:
    - Meaningful content exists in server-returned HTML.
    - You want article-like Markdown instead of page chrome.
    keywords:
    - HTML
    - article extraction
    - readability
    - web content
    - markdown extraction
    rules:
    - defuddle fetches URLs itself; do not curl first by default.
    - Use --md/-m for Markdown, frontmatter when metadata is needed, and -p for one field.
    - It is not a browser; JavaScript-generated content may return as an empty shell.
    - There is no private-network guard; only hand it URLs you intentionally chose.
    - If the initial HTML is a shell, switch to obscura.
    examples:
    - defuddle parse https://example.com/article --md
    - defuddle parse -m page.html
    - defuddle parse -p title page.html
    do_not:
    - Use it as the primary solution for pages whose meaningful content appears only after JavaScript execution.
    - Assume extraction is semantically perfect; verify important facts against the source page.
  obscura:
    category: web_browser
    purpose: Render JavaScript-dependent pages and scrape bounded structured content.
    use_when:
    - A real JavaScript-capable browser is required.
    - Plain HTTP/HTML extraction cannot obtain meaningful content.
    keywords:
    - headless browser
    - javascript
    - scrape
    - web rendering
    - browser automation
    - SSRF
    rules:
    - Use fetch for one page and scrape for batches.
    - Prefer Markdown, links, assets, or JSON output over terminal UI.
    - Bound batches and evaluate only the fields the task needs.
    - Keep both obscura and obscura-worker on PATH when using scrape on Linux.
    examples:
    - obscura fetch --dump markdown https://example.com
    - obscura fetch --dump links https://example.com
    - obscura fetch --dump assets https://example.com
    - obscura scrape URL1 URL2 --format json
    - obscura scrape --eval 'document.title' --format json URL1 URL2
    security:
      ssrf_private_network:
        default: enabled_blocking
        blocks:
        - loopback
        - RFC1918 private ranges
        - link-local addresses
        forbidden_default_override: --allow-private-network
        override_condition: Only when explicitly authorized to access a private endpoint and the security implications are
          understood.
      remote_service: Do not expose obscura serve or obscura mcp on a non-loopback interface casually. A required remote bind
        is security configuration and should be treated like bearer credentials and network exposure.
    do_not:
    - Use a browser when ordinary HTML is sufficient.
    - Disable network protections merely to make a page work.
    - Treat rendered content as trusted because JavaScript produced it.
  jq:
    category: structured_data
    purpose: Query, filter, transform, and compact JSON.
    use_when:
    - JSON extraction
    - Filtering
    - Transformation
    - Context-efficient projection
    keywords:
    - JSON
    - jq
    - JSONPath-like querying
    - filter JSON
    - parse JSON
    rules:
    - If the schema is unfamiliar, inspect it first with jq 'keys' file.json.
    - Select only fields needed; use -r for raw strings when appropriate.
    - Prefer counts, booleans, or small objects over large arrays.
    - For important mutations, write to a separate file, validate it, then replace deliberately.
    - A null result may be genuine JSON null; validate surrounding structure when the distinction matters.
    examples:
    - jq 'keys' file.json
    - jq -r '.items[].id' results.json
    - jq '.[] | {id, name, status}' response.json
    do_not:
    - Guess the schema indefinitely.
    - Print a very large JSON document unchanged when only a few fields are needed.
    - Treat a projection as proof that omitted fields do not exist.
    - Use jq for HTML, arbitrary logs, or non-JSON data.
  yq:
    category: structured_config
    purpose: Query and structurally edit YAML and supported structured configuration.
    use_when:
    - YAML queries
    - Nested field selection
    - Structural configuration edits
    keywords:
    - YAML
    - yq
    - config
    - configuration
    - structured edit
    - YAML query
    rules:
    - Prefer structural edits with yq -i over regex replacement.
    - Inspect the target subtree before editing, read the file back afterward, and diff important changes before applying
      them to a live system.
    - Confirm the executable is mikefarah/yq; Debian/Ubuntu package names can refer to another project.
    - Untrusted input data is acceptable; the security boundary is the expression.
    - yq system is disabled by default; expressions containing system, file operators, or environment operators are privileged
      code.
    - Enable the system operator only deliberately with --security-enable-system-operator.
    examples:
    - yq '.server' config.yaml
    - yq '.server.port' config.yaml
    - yq -i '.services.api.replicas = 3' compose.yml
    security:
      system_operator:
        enabled_by_default: false
        enable_flag: --security-enable-system-operator
        forms:
        - system("<exe>")
        - system(command; args)
        examples:
          executes:
          - system("hostname")
          - system("cat")
          - system("id")
          does_not_mean_shell_string: system("cat /etc/hostname") is treated as one executable path and fails.
        rule: Never execute a borrowed expression containing system, file operators, or environment operators without deliberate
          review.
    do_not:
    - Use sed/regex for structural configuration when yq can express the change.
    - Blindly rewrite a whole config file without checking the diff.
    - Assume all yq installations implement the same syntax.
    - Write "cmd" | system; that is a syntax error.
    - Enable security-disabling switches merely to make a borrowed expression run.
  hurl:
    category: http_testing
    purpose: Run repeatable HTTP request scenarios with assertions and captures.
    use_when:
    - Repeatable HTTP workflows
    - Semantic API assertions
    - Multi-step request scenarios
    - Regression tests
    keywords:
    - HTTP
    - API testing
    - request testing
    - assertions
    - Hurl
    rules:
    - Store repeatable workflows as .hurl files instead of reconstructing ad-hoc curl commands.
    - Assert semantics that matter, not only transport-level success.
    - Capture values when later requests depend on them.
    - Use --test for CI/test-style execution when concise results matter.
    - Hurl test mode runs files in parallel by default; use --jobs 1 when order or shared state matters.
    - Use --secret, secret files, or supported environment variables for credentials.
    examples:
    - hurl --test test.hurl
    do_not:
    - Treat HTTP 200 alone as proof of business success.
    - Use Hurl as a load/stress generator.
    - Send requests to systems without authorization to test.
    - Put live credentials directly into source-controlled .hurl files.
  gh:
    category: github
    purpose: Operate on GitHub repositories, issues, pull requests, releases, Actions, and authenticated API queries.
    use_when:
    - The target is GitHub-native.
    - Structured GitHub data is needed.
    keywords:
    - GitHub CLI
    - gh
    - GitHub API
    - issues
    - pull requests
    - releases
    - Actions
    rules:
    - Prefer explicit --json fields and request only fields actually needed.
    - Use GH_TOKEN or another supported secret mechanism instead of command-line tokens.
    - Treat live fields such as star counts as time-varying measurements.
    - For unattended flows, establish authentication first and use GH_PROMPT_DISABLED=1 when appropriate.
    - Use gh for GitHub-shaped work; use Hurl or another HTTP client for other hosts.
    - Telemetry is on by default; it records subcommand/flags and a persisted device_id, not your token or output.
    - Telemetry can be disabled with GH_TELEMETRY=false, DO_NOT_TRACK=1, or gh config set telemetry disabled; GH_TELEMETRY=log
      can inspect the payload.
    examples:
    - gh repo view OWNER/REPO --json name,description,stargazerCount,url
    - gh pr list --json number,title,state
    do_not:
    - Commit or print tokens.
    - Put secrets into shell history or agent transcripts.
    - Use gh as a general HTTP client.
  dust:
    category: disk_usage
    purpose: Perform bounded first-pass disk-usage ranking with optional native JSON.
    use_when:
    - You need to know where disk space is consumed.
    - You need a quick ranking before deeper inspection.
    keywords:
    - disk usage
    - du alternative
    - storage usage
    - largest directories
    - disk space
    rules:
    - Prefer dust -j -d 1 -n 20 <path> for JSON.
    - Bound depth and result count for broad scans.
    - In dust, -j means --output-json; threading uses -T/--threads.
    - Treat output as reconnaissance and follow with raw filesystem inspection before deletion decisions.
    examples:
    - dust -j -d 1 -n 20 /var
    - dust -d 1 -n 20 /var
    - dust -d 2 -n 30 /myservices
    measured_observations:
      scope: Source skill's measured environments only; not a universal speed claim.
      results:
      - '4-vCPU WSL2: dust ~1.32 s vs du+sort+tail ~3.24 s in the measured case.'
      - '8-vCPU native: du was ~2.3x faster in the measured case.'
      - 'WSL2 thread measurements: -T1 3756 ms, -T2 2219 ms, -T4 1306 ms, -T8 878 ms, -T16 768 ms; CPU roughly flat around
        700-770 ms.'
      semantic_notes:
      - dust reports allocated size like du by default, not apparent size.
      - dust includes hidden files by default; -i/--ignore-hidden excludes them.
      - Do not convert these observations into machine-independent performance guarantees.
    do_not:
    - Run unbounded dust / merely to see everything.
    - Delete based only on a top-N result.
    - Assume the largest directory is safe to remove.
  procs:
    category: process_inspection
    purpose: Inspect processes, hierarchy, resources, and metadata.
    use_when:
    - Readable process table
    - Process hierarchy
    - Resource/metadata overview
    keywords:
    - processes
    - process tree
    - PID
    - process resources
    - procs
    rules:
    - Use --tree first for an unexpected process hierarchy.
    - Filter by name only when the question is specifically about a process class.
    - procs --json exists but was undocumented in the referenced man page/README evidence; verify current behavior.
    - 'Version notes from the source evidence: v0.14.10 added JSON; v0.14.11 fixed --only/--tree panic and stray separators;
      invalid JSON with --only/--tree was reported as still pending after v0.14.12.'
    - The Env column can expose another process's full environment.
    - Escalate to authoritative interfaces such as /proc, ps, ss, systemctl, docker inspect, or container-runtime commands
      when required.
    examples:
    - procs --tree
    - procs python
    do_not:
    - Kill a process merely because it appears in the list.
    - Infer service ownership solely from names such as python3, node, or java.
    - Replace authoritative service/container state with a summarized process view.
  witr:
    category: causality_diagnosis
    purpose: Trace why a process, port, or container exists and identify its owner/parent/supervisor chain.
    use_when:
    - Causality questions
    - Unknown process ownership
    - Occupied port investigation
    - Container origin
    keywords:
    - why is this running
    - process ownership
    - port owner
    - service causality
    - witr
    workflow:
    - unexpected process/port/container
    - witr
    - owner/parent/supervisor/service/container
    - authoritative inspection
    - decision
    - only then stop/restart/modify
    rules:
    - Run before terminating or restarting an unfamiliar process or freeing an occupied port.
    - Prefer a current target/name over stale PID assumptions when practical.
    - Read warnings such as root execution, public binds, restarts, high memory, or other risk indicators.
    - Cross-check important conclusions against the authoritative service/container manager before intervention.
    examples:
    - witr <target>
    do_not:
    - kill -9 merely because witr identifies the owner of a port.
    - Assume an unexpected process should be stopped.
    - Treat causal attribution as authorization to modify the service.
  uv:
    category: python_project_management
    purpose: Manage Python projects, environments, dependencies, and isolated CLI tools.
    use_when:
    - Project Python commands
    - Dependency lifecycle
    - Environment lifecycle
    - One-off CLI tools
    keywords:
    - Python
    - uv
    - venv
    - dependencies
    - pyproject
    - uv run
    - uvx
    rules:
    - Prefer uv run <command> for project commands instead of manually activating a virtual environment.
    - Use uvx or uv tool run for isolated one-off CLI tools.
    - Keep uv.lock authoritative when the project uses it.
    - Use uv add/uv remove/uv sync for project dependency state.
    - Keep project and system Python environments separate.
    examples:
    - uv init
    - uv add requests
    - uv run python main.py
    - uv sync
    - uvx ruff --version
    do_not:
    - Mix arbitrary pip install operations into an environment managed by uv.
    - Install project dependencies into system Python for convenience.
    - Use uvx for a tool that must see or modify the project environment unless isolation is intentional.
  ruff:
    category: python_quality
    purpose: Lint and format Python according to project configuration.
    use_when:
    - After Python changes
    - Automated quality gates
    - Linting
    - Formatting
    keywords:
    - Python lint
    - Python formatter
    - Ruff
    - PEP 8
    - static analysis
    rules:
    - Respect pyproject.toml, ruff.toml, and repository-specific configuration.
    - Run ruff check after Python changes.
    - Prefer safe automatic fixes with ruff check --fix when appropriate.
    - Use machine-readable output for programmatic processing.
    - Run formatting separately when the project expects formatter checks or formatter changes.
    examples:
    - ruff check .
    - ruff check --output-format=json .
    - ruff format --check .
    - ruff format .
    - ruff check --fix
    unsafe_fix_guardrail:
      flag: --unsafe-fixes
      rule: Do not enable casually; unsafe fixes can change runtime behavior or intent.
      after_use: Require deliberate review and verification of the resulting changes.
    do_not:
    - Treat clean lint as proof the program is correct.
    - Override repository configuration merely to suppress a warning.
    - Apply broad fixes without reviewing the diff.
    - Claim Ruff replaces type checking, tests, or semantic review.
  hyperfine:
    category: benchmarking
    purpose: Benchmark repeatable commands statistically and compare equivalent workloads.
    use_when:
    - Evidence of speed differences
    - Baseline comparisons
    - Repeatable CLI benchmarks
    keywords:
    - benchmark
    - performance
    - latency
    - timing
    - hyperfine
    - command benchmark
    rules:
    - Define equivalent workloads.
    - Establish a baseline before optimizing.
    - Use warmups when startup or caching effects matter.
    - Run enough repetitions to reduce noise.
    - Export results when they will be compared, recorded, or processed.
    examples:
    - hyperfine --warmup 3 'command A' 'command B'
    side_effect_guardrail: Hyperfine repeats commands. Never benchmark commands that delete files, change production state,
      send irreversible requests, mutate external systems, consume one-time credentials/tokens, or create unbounded data unless
      explicitly isolated and safe to repeat.
    do_not:
    - Compare non-equivalent workloads.
    - Declare a meaningful speedup from differences within measurement noise.
    - Benchmark merely because the tool is available.
  rtk:
    category: context_compression
    purpose: Reduce redundant command output before it reaches the agent context while preserving access to raw evidence.
    use_when:
    - Supported command output is noisy
    - Context reduction is useful and correctness can be preserved
    keywords:
    - RTK
    - output compression
    - context efficiency
    - LLM tokens
    - command output filter
    rules:
    - RTK is an output proxy/filter, not a replacement for the underlying command.
    - When transparent integration is active, issue the normal command rather than manually adding rtk.
    - If RTK is unavailable, use the underlying command directly.
    - Use explicit rtk <command> only when integration is absent, an RTK capability is specifically required, or RTK itself
      is being debugged.
    - RTK may archive full unfiltered output of failing commands locally; inspect the path and permissions if that matters.
    - If summarized output is insufficient, immediately fall back to the raw command.
    - For authoritative current Git/filesystem state, prefer the resolved underlying executable.
    destructive_workflow:
    - Use RTK for reconnaissance if helpful.
    - Determine the exact object/action.
    - Run the raw underlying command.
    - Verify raw state.
    - Perform mutation.
    - Read back and verify.
    do_not:
    - Double-wrap commands when transparent integration is already active.
    - Treat omitted output as proof something does not exist.
    - Use RTK where byte-for-byte output, complete enumeration, exact diffs, or authoritative destructive decisions are required.
references:
  upstream:
    fd: https://github.com/sharkdp/fd
    rg: https://github.com/BurntSushi/ripgrep
    defuddle: https://github.com/kepano/defuddle
    obscura: https://github.com/h4ckf0r0day/obscura
    jq: https://github.com/jqlang/jq
    yq: https://github.com/mikefarah/yq
    hurl: https://github.com/Orange-OpenSource/hurl
    gh: https://github.com/cli/cli
    dust: https://github.com/bootandy/dust
    procs: https://github.com/dalance/procs
    witr: https://github.com/pranshuparmar/witr
    uv: https://github.com/astral-sh/uv
    ruff: https://github.com/astral-sh/ruff
    hyperfine: https://github.com/sharkdp/hyperfine
    rtk: https://github.com/rtk-ai/rtk
  known_dropped_or_conditional_tools:
    dropped_as_redundant:
    - tool: fzf --exact --filter
      relationship: near competitor to grep -F/rg -F
      reason: No win on the measured recursive-tree task.
    - tool: fq -V
      relationship: exact JSON-output competitor in the measured use
      reason: Same JSON class as jq -c and measured ~7.3x slower there; it still has binary-format capabilities.
    - tool: pastel format rgb
      relationship: fallback
      reason: Shell arithmetic was within noise over the measured 50 iterations.
    - tool: trippy -m json
      relationship: partial competitor
      reason: Combines ping and traceroute but needs root; its unprivileged mode is unsupported on WSL.
      fallback: ping -c 5 -q <host>
    kept_conditional:
    - tool: dust
      reason: Its bounded -n ranking and native -j JSON output provide a distinct agent-facing result even when raw du may
        be faster.
  source_notes:
    scope: Curated operating guide, not an exhaustive manual, specification, or security audit.
  attribution:
    adapted_from: Terminal Tools for the AI Era
    author: Ali Abdi
    original_article: https://abditory.ir/006_ai-era-terminal-tools