Agent-Friendly CLI Design Best Practices

Prescriptive design and review standards for Command-Line Interface Design targeting AI agents and scripts, not just humans typing at a prompt. Human-oriented CLIs often block agents: interactive prompts, huge upfront docs, help text without copy-pasteable examples, error messages without fixes, no dry-run mode. This skill prioritizes rules by blast radius — from "the agent cannot use this CLI at all" (CRITICAL) to "the agent has to read help one extra time" (MEDIUM).

Use this skill both when building a new CLI and when reviewing an existing one for agent-friendliness.

This skill contains 45 rules across 8 categories.

When to Apply

Reference these guidelines when:

• Writing --help text for any subcommand
• Designing new flags, arguments, or subcommands
• Crafting error messages or exit codes
• Adding destructive operations that need dry-run or confirmation
• Choosing between interactive prompts and flag-only inputs
• Shaping success output so agents can chain commands
• Reviewing an existing CLI for headless-usability regressions

Rule Categories by Priority