cli-for-agents · pproenca — Claude Code skill: what it does, how to install
cli-for-agents is a Claude Code skill for designing and reviewing CLIs used by AI agents and automation. It applies to work on subcommands, flags, help text, and error messages.
MIT 237 installs ★ 227 updated 2026-08-15
npx skills add pproenca/dot-skills --skill cli-for-agents -a claude-codeWhat cli-for-agents does
The skill sets design rules for command-line tools that agents and scripts will use. Its guidance covers non-interactive operation, example-rich help, actionable errors, and safer destructive commands. It also addresses input, output, retries, and command structure.
The rules call for options such as --no-input, --dry-run, and --json, and for errors to include a concrete fix. The skill applies both when building a CLI and when reviewing an existing one. It is triggered by tasks such as writing --help or adding a subcommand, even if agent usability was not requested explicitly.
There are 45 rules in 8 priority-ranked categories. For destructive commands, the guidance includes dry runs and confirmation; help should contain examples that can be copied into a terminal.
What it helps with
- design a CLI that works without interactive prompts
- add runnable examples to
--helpoutput - write errors with a concrete fix
- add safeguards for destructive commands
- format CLI output for use by another command
Example prompts for the agent
- Review this CLI for problems in non-interactive runs.
- Suggest flags and
--helptext for a new subcommand. - Rewrite the CLI errors and suggest safeguards for delete operations.
How to install cli-for-agents
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill cli-for-agents -a claude-code2Manually: put the files in place
~/.claude/skills/cli-for-agents/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/cli-for-agents/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill cli-for-agents -a codex2Manually: put the files in place
.agents/skills/cli-for-agents/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill cli-for-agents -a cursor2Manually: put the files in place
.cursor/skills/cli-for-agents/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pproenca/dot-skills skills/.experimental/cli-for-agents2Manually: put the files in place
.github/skills/cli-for-agents/SKILL.md1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill cli-for-agents -a gemini-cli2Platform CLI
gemini skills install https://github.com/pproenca/dot-skills --path skills/.experimental/cli-for-agentsManually: put the files in place
.devin/skills/cli-for-agents/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill cli-for-agents -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about cli-for-agents
How do I install cli-for-agents in Claude Code?
Run npx skills add pproenca/dot-skills --skill cli-for-agents -a claude-code. The skill file is at ~/.claude/skills/cli-for-agents/SKILL.md.
What does cli-for-agents do?
It provides rules for building and reviewing CLIs used by AI agents and scripts, covering flags, help, errors, output, and safe command behavior.
When does cli-for-agents apply?
Use it while building a CLI or reviewing an existing one. It also applies to tasks such as writing --help, adding a subcommand, or designing error messages.
Source text
SKILL.md · MIT
--- name: cli-for-agents description: Designing CLIs that AI agents will invoke — non-interactive flags, layered --help with examples, stdin/pipeline composition, actionable errors, idempotency, dry-run, destructive-action safety, and predictable command structure. Use when designing, building, or reviewing a command-line tool that AI agents or automation will invoke. 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) - [`interact-flags-first`](references/interact-flags-first.md) — Express every input as a flag first; prompts are TTY-only fallback - [`interact-detect-tty`](references/interact-detect-tty.md) — Check `isatty()` before prompting - [`interact-no-arrow-menus`](references/interact-no-arrow-menus.md) — Replace arrow-key menus with flag-selected choices - [`interact-no-input-flag`](references/interact-no-input-flag.md) — Support `--no-input` to force non-interactive mode - [`interact-no-timed-prompts`](references/interact-no-timed-prompts.md) — Never use timed prompts or press-any-key screens - [`interact-no-hang-on-stdin`](references/interact-no-hang-on-stdin.md) — Don't block on stdin when a TTY is attached ### 2. Help Text Design (HIGH) - [`help-examples-in-help`](references/help-examples-in-help.md) — Include copy-pasteable examples in every `--help` - [`help-per-subcommand`](references/help-per-subcommand.md) — Every subcommand owns its own `--help` - [`help-no-flag-required`](references/help-no-flag-required.md) — Show help when invoked with zero arguments - [`help-layered-discovery`](references/help-layered-discovery.md) — Top-level help is a navigational index - [`help-flag-summary`](references/help-flag-summary.md) — List both short and long forms for every flag - [`help-suggest-next-steps`](references/help-suggest-next-steps.md) — Suggest what to run next in help and success output ### 3. Error Messages (HIGH) - [`err-exit-fast-on-missing-required`](references/err-exit-fast-on-missing-required.md) — Exit fast on missing required flags - [`err-actionable-fix`](references/err-actionable-fix.md) — Include a concrete fix in every error message - [`err-stderr-not-stdout`](references/err-stderr-not-stdout.md) — Send errors to stderr, not stdout - [`err-non-zero-exit-codes`](references/err-non-zero-exit-codes.md) — Use distinct non-zero exit codes for distinct failures - [`err-include-example-invocation`](references/err-include-example-invocation.md) — Include a correct example invocation in errors - [`err-no-stack-traces-by-default`](references/err-no-stack-traces-by-default.md) — Reserve stack traces for `--debug` mode ### 4. Destructive Action Safety (HIGH) - [`safe-dry-run-flag`](references/safe-dry-run-flag.md) — Provide `--dry-run` for every destructive command - [`safe-force-bypass-flag`](references/safe-force-bypass-flag.md) — Provide `--yes` / `--force` to skip confirmations - [`safe-confirm-by-typing-name`](references/safe-confirm-by-typing-name.md) — Require typing the resource name for irreversible actions - [`safe-no-prompts-with-no-input`](references/safe-no-prompts-with-no-input.md) — Never prompt when `--no-input` is set - [`safe-idempotent-cleanup`](references/safe-idempotent-cleanup.md) — Exit successfully when delete targets are already gone - [`safe-crash-only-recovery`](references/safe-crash-only-recovery.md) — Design multi-step commands for crash-only recovery ### 5. Input Handling (HIGH) - [`input-accept-stdin-dash`](references/input-accept-stdin-dash.md) — Accept `-` as filename for stdin and stdout - [`input-flags-over-positional`](references/input-flags-over-positional.md) — Prefer named flags over positional arguments - [`input-stdin-for-secrets`](references/input-stdin-for-secrets.md) — Accept secrets through stdin or file, never as flag values - [`input-env-var-fallback`](references/input-env-var-fallback.md) — Accept common flags through environment variables - [`input-no-prompt-fallback`](references/input-no-prompt-fallback.md) — Never fall back to a prompt when a flag is missing ### 6. Output Format (MEDIUM-HIGH) - [`output-json-flag`](references/output-json-flag.md) — Provide `--json` for stable machine-readable output - [`output-ndjson-streaming`](references/output-ndjson-streaming.md) — Stream large result sets as NDJSON - [`output-bounded-by-default`](references/output-bounded-by-default.md) — Bound default output size with `--limit` and `--all` - [`output-machine-ids-on-success`](references/output-machine-ids-on-success.md) — Return chainable values on success, not just "Done" - [`output-respect-no-color`](references/output-respect-no-color.md) — Disable ANSI color when `NO_COLOR` or non-TTY - [`output-no-decorative-only`](references/output-no-decorative-only.md) — Avoid relying on decorative output to convey state - [`output-one-record-per-line`](references/output-one-record-per-line.md) — One record per line for grep-able human output ### 7. Idempotency & Retries (MEDIUM-HIGH) - [`idem-retry-safe`](references/idem-retry-safe.md) — Make running the same command twice safe - [`idem-create-or-skip`](references/idem-create-or-skip.md) — Make create commands skip when target already exists - [`idem-stable-output-on-skip`](references/idem-stable-output-on-skip.md) — Return the same output shape whether acting or skipping - [`idem-state-reconciliation`](references/idem-state-reconciliation.md) — Prefer "ensure state" semantics over delta application - [`idem-stable-identifiers`](references/idem-stable-identifiers.md) — Accept user-provided names instead of auto-generating IDs ### 8. Command Structure (MEDIUM) - [`struct-resource-verb`](references/struct-resource-verb.md) — Use a consistent resource-verb command shape - [`struct-flag-order-independent`](references/struct-flag-order-independent.md) — Parse flags in any position relative to subcommands - [`struct-no-hidden-subcommand-catchall`](references/struct-no-hidden-subcommand-catchall.md) — Avoid catch-all handlers for unknown subcommands - [`struct-standard-flag-names`](references/struct-standard-flag-names.md) — Use standard flag names (`--help`, `--version`, `--verbose`, `--quiet`) ## 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: 1. **Non-interactive path** — invoke every subcommand with `--no-input` or under `</dev/null` and see which hang 2. **Layered help** — does `mycli --help` list subcommands only, or dump everything? 3. **Examples on `--help`** — every subcommand's help should end with a runnable Examples section 4. **Error messages with invocations** — does every error tell the caller exactly which flag to add? 5. **stdin/pipeline story** — can you pipe output into input? Does `-` mean stdin? 6. **Exit codes** — are usage errors (2), runtime failures (1), and transient failures (69) distinct? 7. **Dry-run** — every destructive command has `--dry-run` (or equivalent) 8. **Confirmation bypass** — every destructive command has `--yes`/`--force` 9. **Consistent command structure** — do `service list`, `deploy list`, `config list` all exist and work the same way? 10. **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: - [Section definitions](references/_sections.md) — Category structure and impact levels - [Rule template](assets/templates/_template.md) — Template for adding new rules ## Reference Files | File | Description | |------|-------------| | [references/_sections.md](references/_sections.md) | Category definitions and ordering | | [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules | | [metadata.json](metadata.json) | Version and reference information |
© pproenca · MIT · pproenca/dot-skills
Similar skills
All skills for Agent setup: memory, context, orchestration →cli-for-agents by other authors comes first.