agent-ergonomics-and-intuitiveness-maximization-for-cli-tools
Made by JeffScore and aggressively improve CLI ergonomics for AI agents. Use when auditing agent-friendly CLI UX, robot/json modes, help/errors, or applying fixes in-tree.
Works With
Quality and Utility come from canonical skill metadata. Community ratings appear separately as stars when subscriber reviews exist.
Subscribe to download
Public previews are available, but downloads, CLI sync, and premium content require an active subscription.
Sign In to Subscribe- Full skill content with deterministic versioning
- CLI sync + local search index
- Access to Jeffrey’s premium library
Save to your account
Saved skills live in your cloud list. Run jsm sync on each machine to pull them locally.
What's New with this Skill
2Updates, enhancements, and release notes for this skill.
Enhanced: agent-ergonomics, the NTM swarm section now runs as written
The swarm-tier audit section was written against an NTM that never existed: ntm new, named panes, --agent= and --message= flags. Every command was rewritten against the live binary, so a multi-binary family audit can be pasted and run end to end.
- Fictional verbs replaced: ntm new, ntm exec and ntm restart became spawn --label, send --pane, and --robot-restart-pane with its dry-run preview; status checks use --robot-status and --robot-is-working
- Panes are indexed, not named; the recipes state their tmux base-index-0 assumption and brief workers at panes 0 through 4
- Rate-limit triage reads the per-provider pools rollup from --robot-health-oauth instead of a fictional ntm panes --filter=rate-limited
New: agent-ergonomics-and-intuitiveness-maximization-for-cli-tools, score every surface, fix the worst, prove the lift
Most CLI tools were designed for humans at a terminal. When an agent is the primary user, the same tool becomes a friction surface several times an hour. This skill scores every subcommand, flag, error, and capability endpoint from 0–1000 across an 11-dimension rubric, ranks the worst by frequency × score_gap × blast_radius, applies the highest-leverage fixes on a feature branch, and re-scores to prove the lift held. All artifacts persist as JSONL so the next pass can compare against this one.
- Eleven scoring dimensions: agent_intuitiveness, agent_ergonomics, agent_ease_of_use, output_parseability, error_pedagogy, intent_inference, safety_with_recovery, determinism_and_reproducibility, self_documentation, composability, regression_resistance; each anchored at 0/250/500/750/1000
- Ten-phase loop from surface inventory through handoff. Phases 4–7 (recommend, apply, re-score, fresh-eyes) reapply until quiet: median uplift drops below 25 points and no surface regresses by more than 50
- Polish bar is twelve hard tests every shipped surface must pass: first-try success, JSON everywhere, capabilities endpoint, robot-docs, mega-command, exit-code contract, error pedagogy, intent inference, dangerous-op gating, deterministic output, NO_COLOR/CI honored, regression test landed
- Every above-700 score must cite source-line evidence or a runtime transcript; validate_scorecard.sh rejects vibe-check scoring
- Priority is frequency × score_gap × blast_radius, so recommendations are ranked by where an agent actually feels the friction, not where the score is technically lowest
- Per-recommendation regression test lands as a golden snapshot in audit/regression_tests/, named after the recommendation ID, so the ergonomics fix can't silently rot
- Triangulation in Phase 4 (synthesizing recommendations) and Phase 7 (fresh-eyes review) uses peer-Claude by default, multi-model (Codex / Gemini) when available; independent reads catch what a single scorer misses
- Audit workspace lives as a sibling repo (<target>__agent_ergonomics_audit/); code changes happen in-tree on a feature branch in the target repo so the audit artifacts and the actual fixes never tangle
- Resumable: pass 1 produces baseline, pass 2 re-runs against the changed code and reports uplift, and single-surface-rescore re-scores one surface_id after a targeted fix
- Ships an agent-ergonomics-check GitHub Action for PRs: it fails when a scored surface disappears without a deprecation path and flags new surfaces for the next full pass
The audit runs a ten-phase loop on the target repo: surface inventory, rubric-driven scoring, an intent-inference stress test, recommendation synthesis, apply, re-score, fresh-eyes review, self-documentation hardening, agent-in-the-loop verification, and handoff. The core steps work like this. Inventory walks every surface an agent will actually touch (subcommand tree, flag spelling, exit codes, error-message corpus, env vars, completion scripts, config-file schemas, signal handlers) and assigns each one a stable surface_id. Score runs the 11-dimension rubric with two scorers per surfa