AI-Friendly CLI Design

Use this skill when public CLI behavior affects how an Agent discovers safe usage, runs a command, reads the result, recovers from failure, or chooses the next action.

Core judgment:

A CLI command is not only an execution surface. It is a context delivery surface for the next Agent step.

Golden Principles

Help is part of the interface. A command's help should explain why an Agent would call it, what input shape it expects, what output modes exist, what can go wrong, and what a likely next step looks like.

Output is context, not just result. Normal output should carry enough state for an Agent to continue without reconstructing hidden context.

Defaults should be token-aware. Repeated Agent loops need useful, bounded output by default; detail should be opt-in and discoverable.

JSON stdout is a contract. Machine-readable output must stay parseable, stable, and free of logs, banners, or prose.

Ambiguity belongs in the output. If a command is matching, guessing, filtering, truncating, or returning candidates, say so directly.