Document modern CLI speed tools and best practices

[klh]

Added a section on modern CLI speed tools with comparisons to traditional commands, including usage examples and benchmarks.

[Copilot]

Pull request overview

Adds a new “CLI Speed Tools” section to CLAUDE.md to guide contributors toward faster modern CLI utilities and workflow patterns, with example one-liners and a benchmark comparison table.

Changes:

• Documents recommended modern CLI replacements for filesystem operations, HTTP/API calls, and Git/DevOps workflows.
• Adds workflow optimization rules focused on reducing multi-file tool-call overhead via pipelines and parallelism.
• Includes a benchmarks table with claimed speedups for common operations.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[nucliweb]

Really like the direction here. A curated set of fast, reliable CLIs is genuinely valuable for agent workflows, and the benchmarks make the case concrete. I do think there are two structural issues worth resolving before this lands, plus a few smaller things, and one follow-up direction I would love to explore.

1. Modern tools are assumed installed, with no conditional or fallback

The section reads as a hard rule set ("NEVER", "ALWAYS", "Use these whenever terminal operations are needed") for ~30 external binaries: eza, rg, fd, bat, sd, amber/ambr, sad, dust, procs, difft, batdiff, delta, batgrep, xcp, zoxide, tokei, doggo, watchexec, lazygit, xh, aria2, hurl, git-standup, act, actionlint, shellcheck, plus tree and jq. An agent picking this up in an environment that only has POSIX tools will either fail, ignore the rule silently, or try to install things without consent.

Suggestions:

• Add a "Prerequisites" subsection with install hints (brew install ..., cargo install ..., package names per distro).
• Reframe the imperative as conditional: "If rg is available, prefer it over grep -r. Otherwise use grep -r --include='*.ts'." This is closer to how a senior engineer would actually write the rule.
• Optional: a one-liner the agent can run to detect availability (command -v rg >/dev/null && ...).

2. Project CLAUDE.md is the wrong surface for this

This guidance lives only in the project's CLAUDE.md, which only applies when working inside agent-skills itself. The whole point of this repo is to publish skills that other users install; this content does not propagate to them. The impact outside this repo is effectively zero today.

Also, the Boundaries section in the same file says: "Never: Add skills that are vague advice instead of actionable processes" and "Never: Duplicate content between skills, reference other skills instead." A 191-line rule set inside CLAUDE.md runs against both.

Two paths forward that would have actual leverage:

• Promote to a Skill: skills/cli-speed-tools/SKILL.md with YAML frontmatter, When to Use, Process, Common Rationalizations, Red Flags, Verification. This is the documented pattern in the repo and gets it into the skill discovery flow.
• Promote to a reference: references/cli-speed-tools.md, and have existing skills link to it from the places it actually applies:
  • git-workflow-and-versioning for difft, delta, git log -L.
  • debugging-and-error-recovery and context-engineering for rg, fd, batgrep.
  • code-review-and-quality for structural diffs.

Either is more useful than the current placement.

Smaller things

• "10-1400x faster" in the opening line is misleading. The 1400x number compares a Claude Read+Edit workflow (with per-tool-call overhead) against a shell pipeline. Those are different units of work. Methodology note further down already acknowledges this; the opening should match. Something like "often 10x to 100x faster on common operations" reads more honestly.
• Absolute rules like "NEVER pipe file listings into while/read loops" and "ALWAYS use parallel execution" are too strong for guidance aimed at agents. Prefer "default to X; reach for Y only when ..."
• macOS-specific notes (BSD sed, NFS) should be marked as such, otherwise they read as universal.
• xcp "10x faster on NFS" is a narrow case; consider dropping the number or noting it only matters on networked filesystems.
• tree -J | jq patterns: tree is itself an extra dependency on many systems and overlaps with fd/eza --tree. Worth picking one and being consistent.

Follow-up: agent-first CLIs

One direction I think is worth investigating, possibly as a sibling reference or a second skill, is "agent-first" CLIs: tools designed from the start to be driven by an LLM or an agent rather than a human at a terminal. The tools in this PR are "human-fast" (great UX, color, fuzzy search, TUIs), which is not always the same thing as "agent-friendly". For an agent, the properties that matter more are usually:

• Structured output by default or via a flag (--json, --ndjson).
• 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.

gh, jq, kubectl -o json, and actionlint already fit this shape well. There are newer ones explicitly framing themselves this way, and I would be interested in mapping which of those are mature enough to recommend. Happy to open a separate issue to track that if it sounds useful.