Investigate "agent-first" CLIs and document their use across skills

[nucliweb]

Background

Spun off from #29 ("CLI Speed Tools" PR), where the discussion surfaced that "human-fast" tools (rg, fd, bat, eza, dust, ...) optimize for human ergonomics, which is not always the same as "agent-friendly". For an agent that consumes CLI output as text and pays a per-tool-call cost, the properties that matter most are different.

Worth tracking this independently, since #29 may end up scoped only to the project's CLAUDE.md and the agent-first angle is broader: it should inform guidance inside the existing skills, not just one document in this repo.

What "agent-first" means here

Tools designed to be driven by an LLM or an agent, rather than by a human at a terminal. The properties that matter:

• Structured output by default or via a flag (--json, --ndjson, -o json).
• Stable, parseable exit codes and machine-readable error messages.
• Idempotent or dry-run modes for safe exploration.
• No interactive prompts, or a clean non-interactive flag.
• Predictable, deterministic output across runs (no random ordering, no spinners in the pipe).
• Low startup overhead (matters when an agent issues many short calls).

Tools that already fit the shape

Non-exhaustive starting list:

• gh (GitHub CLI), first-class --json and --jq.
• jq, designed for piping structured data.
• kubectl -o json / -o yaml.
• actionlint, predictable diagnostics with clear exit codes.
• shellcheck -f json.

Worth researching:

• Newer CLIs that explicitly frame themselves as agent-friendly or LLM-friendly.
• Whether nushell patterns transfer (everything is structured by default).
• Which tools listed in Document modern CLI speed tools and best practices #29 also have a usable structured-output path (e.g. rg --json, fd --print0, delta exit codes).

Proposed scope

1. Survey: which CLIs in current use across the skills have first-class structured output, deterministic behavior, and clean non-interactive modes.
2. Recommend defaults per skill where it matters:
   • debugging-and-error-recovery and context-engineering for search and read.
   • git-workflow-and-versioning for diff and history.
   • code-review-and-quality for static analysis output.
   • ci-cd-and-automation for pipeline linting.
3. Produce a references/agent-first-clis.md and link from the relevant skills, rather than adding a new top-level skill.

Open questions

• Should this live as a new skill or only as a reference cross-linked from existing skills?
• Where does the line between "fast for humans" and "good for agents" sit, and which tools satisfy both?
• Should there be a small command -v preflight pattern shared across skills that depend on optional tools?

Happy to take this on once direction is agreed.

[Danbakarya2023]

how may help you sir !

[nucliweb]

Thanks, @Danbakarya2023. The issue is open for research; if you'd like to contribute, share any agent-first CLIs you come across (with notes on structured output, exit codes, and non-interactive modes) as a comment here.