| name | cli-standards |
| description | Define, implement, and review command-line interface behavior for CLI tools. Use when designing commands/subcommands, flags/args, help text, stdout/stderr contracts, exit codes, interactivity, and automation compatibility. |
| compatibility | Generic skill for coding agents and CLI projects; references POSIX utility conventions, GNU CLI standards, gitcli conventions, and clig.dev best practices. |
| metadata | {"author":"sanchuanhehe","version":"1.0"} |
CLI Standards Skill
Purpose
Use this skill to keep a CLI predictable, script-friendly, and human-friendly.
Primary references:
- POSIX Utility Conventions (argument syntax and ordering baseline)
- GNU CLI standards (
--help, --version, long options)
- Git CLI conventions (disambiguation with
--, options-before-args discipline)
- CLIG (human-first UX, errors, output, discoverability)
- External Standards Reference (compiled URLs and key points)
When to activate
Activate when the task includes any of the following:
- Add or change command/subcommand structure
- Add or rename flags/options/arguments
- Change help text, usage, examples, or docs
- Change stdout/stderr format, logs, progress, or JSON output
- Change exit codes or error handling
- Add interactive prompts, confirmations, or non-interactive mode
Non-negotiable defaults
- Options before operands by default.
- Support
-h and --help; both must show help and exit successfully.
- Support
--version; print version information to stdout and exit successfully.
- Primary output to stdout; diagnostics/errors/progress to stderr.
- Exit code
0 for success, non-zero for failure.
- Support
-- to end option parsing when operands may start with -.
- Avoid breaking existing flags/subcommands; prefer additive changes.
Design workflow
Step 1: Command model
- Prefer explicit subcommands for complex workflows.
- Keep naming consistent across subcommands.
- Avoid ambiguous command names (
update vs upgrade) unless clearly distinct.
Step 2: Args and Flags
- Prefer flags over too many positional args.
- Provide both short and long forms for high-frequency options.
- Use standard names where possible:
-h, --help--version-v/--verbose (pick one semantics and stay consistent)-q, --quiet-n, --dry-run-f, --force-o, --output
- In script examples, use fully spelled-out long option names.
Step 3: Output Contract
- Human-readable default output.
- If machine integration is needed, provide
--json (or an equivalent stable format).
- Do not mix parseable data with log lines on stdout.
- If output is long, use a pager only for interactive TTY.
Step 4: Errors and UX
- Error messages should be actionable: what failed + why + next fix.
- If a typo is likely, suggest the closest command or flag.
- For destructive actions, confirm in interactive mode; require an explicit force/confirm flag in non-interactive mode.
- Never require prompts in CI or script mode.
Step 5: Compatibility and Evolution
- Keep existing behavior stable unless a major version migration is explicit.
- If deprecating, warn clearly and provide a replacement path.
- Preserve automation paths (
--no-input, --json, stable exit semantics).
Priority when standards conflict
- Project-specific compatibility requirements (existing CLI contract)
- POSIX conventions (syntax/order/disambiguation baseline)
- GNU conventions (
--help, --version, long options)
- Git CLI and CLIG practices (usability/script robustness)
Deliverables expected from agent
For each CLI change, produce:
- Updated command/flag design.
- Updated help output/examples.
- Explicit stdout/stderr and exit code behavior.
- Backward-compatibility note.
- Validation results using references/checklist.md.
Quick references
