| name | cli-for-agents |
| description | Use this skill whenever designing, building, or reviewing a command-line tool that AI agents or automation will invoke — covers non-interactive flags, layered --help with examples, stdin/pipeline composition, actionable errors, idempotency, dry-run, destructive-action safety, and predictable command structure. Trigger even if the user doesn't explicitly say "agent-friendly" — apply whenever they are writing `--help` text, adding a new subcommand, designing error messages, or reviewing a CLI's UX. |
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
| Priority | Category | Impact | Prefix |
|---|
| 1 | Non-interactive Operation | CRITICAL | interact- |
| 2 | Help Text Design | HIGH | help- |
| 3 | Error Messages | HIGH | err- |
| 4 | Destructive Action Safety | HIGH | safe- |
| 5 | Input Handling | HIGH | input- |
| 6 | Output Format | MEDIUM-HIGH | output- |
| 7 | Idempotency & Retries | MEDIUM-HIGH | idem- |
| 8 | Command Structure | MEDIUM | struct- |
Note: help-examples-in-help is rated CRITICAL within the HIGH help- category because its specific failure — help text without examples — makes every other help rule moot. The category label reflects the average, not the worst case.
Quick Reference
1. Non-interactive Operation (CRITICAL)
2. Help Text Design (HIGH)
3. Error Messages (HIGH)
4. Destructive Action Safety (HIGH)
5. Input Handling (HIGH)
6. Output Format (MEDIUM-HIGH)
7. Idempotency & Retries (MEDIUM-HIGH)
8. Command Structure (MEDIUM)
How to Use
When building a new CLI
Start at CRITICAL and walk down. The first two categories (interact- and help-) are non-negotiable — if any rule in these is violated, the CLI is unusable by agents regardless of how good the rest is. After those, work through err-, safe-, and input- — these are where most real-world friction lives. output-, idem-, and struct- are polish that compounds across many invocations.
When reviewing an existing CLI
Run through this checklist in priority order:
- Non-interactive path — invoke every subcommand with
--no-input or under </dev/null and see which hang
- Layered help — does
mycli --help list subcommands only, or dump everything?
- Examples on
--help — every subcommand's help should end with a runnable Examples section
- Error messages with invocations — does every error tell the caller exactly which flag to add?
- stdin/pipeline story — can you pipe output into input? Does
- mean stdin?
- Exit codes — are usage errors (2), runtime failures (1), and transient failures (69) distinct?
- Dry-run — every destructive command has
--dry-run (or equivalent)
- Confirmation bypass — every destructive command has
--yes/--force
- Consistent command structure — do
service list, deploy list, config list all exist and work the same way?
- Structured success output — does
deploy return a deploy_id the agent can use next?
Individual rules
Read individual reference files for detailed explanations and code examples:
Reference Files
