Agent-Friendly CLI Design & Evaluation

Build command-line tools that AI agents consume reliably and humans use comfortably. These goals are orthogonal — a CLI can serve both audiences from the same command surface by detecting context (TTY vs pipe) and adapting output.

Build mode (default) — walk through Phases 1-6 to construct an agent-first CLI from scratch or retrofit an existing one. Evaluate mode — activated when the user says "score", "evaluate", "audit", or "rate" — jump to Phase 7 to score a CLI on the 7-axis rubric.

This skill targets command-based CLIs (like git, docker, gh, kubectl) — tools with subcommands, flags, and structured output. Not for full-screen TUI applications, dashboards, or GUI tools.

Quick Decision Guide

Hard Gates

Violation of any gate halts progress. No workaround. No exceptions.

Phase 1: Command Design

Design the command surface: grammar, subcommand hierarchy, flag conventions, and naming standards. Pick noun-verb (mycli pod list) or verb-noun (mycli list pods) and apply consistently. Limit hierarchy to 2-3 levels. Prefer flags over positional arguments — flags are self-documenting and order-independent.

Define global flags available on every command: --json, --quiet, --verbose, --no-color, --help, --version. Load references/command-design.md for grammar patterns, flag type conventions, and the backward compatibility contract.

Phase 2: Output Architecture

Implement the JSON envelope, NDJSON streaming, field selection, and TTY-aware dual-mode output. Every command outputs human-readable tables when stdout is a TTY and clean JSON when piped or --json is passed. Every output — success or failure — guides the next action with suggested commands.

Add --fields for context window discipline (agents select only needed columns, reducing token cost by 90%+). Add --limit and cursor-based pagination for large result sets. Load references/output-design.md for envelope schema, NDJSON rules, and token efficiency benchmarks.

Phase 3: Input Handling

Support raw JSON input (--data '{"key":"val"}') alongside individual flags. Accept stdin pipes for batch operations. Harden all inputs against agent-specific failure modes: path traversal (../../.ssh/id_rsa), control character injection (\x00, \x1b), shell metacharacters (;, $(), backticks), double encoding, and embedded query params in resource IDs.

The agent is not a trusted operator — validate at the CLI boundary, fail closed. Load references/input-security.md for attack patterns, mitigation code, and the security posture.

Phase 4: Discoverability & Schema

Implement --help with examples (the most-read section), flag types, defaults, allowed values, exit codes, and see-also. Add --help-json for machine-readable schema introspection — agents use this to discover commands without pre-stuffed documentation.

Generate shell completions (bash, zsh, fish) via framework tooling. Create CONTEXT.md and AGENTS.md knowledge files for agent consumption. Load references/discoverability.md for help text structure, --help-json schema, and knowledge file templates.

Phase 5: Safety & Composability

Add --dry-run on every mutating command — output planned changes as structured JSON. Make operations idempotent (--if-not-exists for create, safe retry for update/delete). Design commands for pipe composition: create outputs the resource ID, list supports --fields and --quiet, action commands accept IDs as flags.

Implement config precedence: flags > env vars > project config > user config > defaults. Handle SIGINT (exit 130), SIGTERM (exit 143), SIGPIPE (exit 141 silently). Load references/composability-safety.md for pipe patterns, signal handling, and backward compatibility rules.

Phase 6: Agent Knowledge Packaging

Ship knowledge files alongside the CLI:

• CONTEXT.md — purpose, authentication, commands, workflows, error codes, agent-specific notes, limitations (under 3000 words)
• AGENTS.md — cross-agent instructions pointing to CONTEXT.md with rules and preferred patterns
• llms.txt — minimal orientation for LLM project scanning

For advanced integration, wrap CLI commands as MCP tools with typed input schemas, or ship Claude Code skill files with guardrails. Load references/agent-knowledge.md for templates and packaging strategies.

Phase 7: Evaluate (optional)

Score the CLI on 7 axes (0-3 each, 0-21 total):

0-5 = Human-only, 6-10 = Agent-tolerant, 11-15 = Agent-ready, 16-21 = Agent-first. Load references/scoring-rubric.md for full per-level criteria, evaluation procedure, and example scores for gh, aws, kubectl, and docker.

Common Mistakes

Reference Files

Rules

1. Agent is not a trusted operator — validate all input at the CLI boundary, fail closed on uncertain validation, sandbox output paths
2. Output guides the next action — every command's output (success, failure, partial) tells the consumer what to do next
3. Structured output is a versioned contract — adding optional fields is safe, removing or renaming fields is breaking
4. TTY detection governs mode — human-readable when interactive, machine-readable when piped, --json overrides both
5. Token cost is a design constraint — every unnecessary byte in stdout costs the agent context window and API spend
6. Framework boilerplate first — load references/framework-patterns.md for the target language before writing code
7. Evaluate after building — run Phase 7 scoring to identify gaps, prioritize lowest-scoring axes

Downstream Handoff

After building an agent-friendly CLI:

• an acceptance-spec / ATDD skill — write acceptance specifications with a CLI protocol driver (command execution, exit code assertions, JSON output parsing)
• an exploratory-QA skill — exploratory testing of the CLI as a user/agent would actually consume it