К основному содержанию
скилл CX Codex

cli-for-agents · pproenca — скилл для Claude Code: что делает и как установить

Скилл cli-for-agents для Claude Code помогает проектировать и проверять CLI, которым пользуются ИИ-агенты и автоматизация. Он включается при работе с подкомандами, флагами, справкой и сообщениями об ошибках.

MIT 237 установок ★ 227 обновлён 2026-08-15

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add pproenca/dot-skills --skill cli-for-agents -a claude-code
Открыть на GitHub

Что делает cli-for-agents

Скилл задаёт правила проектирования командной строки для ИИ-агентов и скриптов. Он охватывает неинтерактивный запуск, справку с примерами, обработку ошибок и безопасные разрушительные действия. Также разбирает ввод и вывод, повторные запуски и структуру команд.

Правила помогают предусмотреть --no-input, --dry-run и машинный вывод через --json, а сообщения об ошибках снабдить конкретным исправлением. Скилл применяет и при создании CLI, и при проверке существующего инструмента; он срабатывает при написании --help или проектировании новой подкоманды, даже без просьбы сделать интерфейс удобным для агентов.

Внутри 45 правил, распределённых по 8 категориям с разными приоритетами. Например, для разрушительных команд описаны пробный запуск и подтверждение, а для справки — примеры, которые можно скопировать.

Какие задачи решает

  • спроектировать CLI без обязательных интерактивных запросов
  • добавить примеры вызовов в справку --help
  • сформулировать ошибки с конкретным способом исправления
  • предусмотреть безопасный запуск разрушительных команд
  • подготовить вывод CLI для передачи в следующую команду

Примеры запросов агенту

  • Проверь CLI на проблемы при запуске без интерактивного ввода.
  • Предложи флаги и справку --help для новой подкоманды.
  • Переработай ошибки CLI и добавь рекомендации по безопасному удалению.

Как установить cli-for-agents

1Через Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill cli-for-agents -a claude-code

2Вручную: положить файлы

~/.claude/skills/cli-for-agents/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/cli-for-agents/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о cli-for-agents

Как установить cli-for-agents в Claude Code?

Выполните npx skills add pproenca/dot-skills --skill cli-for-agents -a claude-code. Файл скилла находится по пути ~/.claude/skills/cli-for-agents/SKILL.md.

Что делает cli-for-agents?

Скилл содержит правила для проектирования и проверки CLI, которыми пользуются ИИ-агенты и скрипты: от флагов и справки до ошибок, вывода и безопасных действий.

Когда срабатывает cli-for-agents?

Используйте его при создании CLI или проверке существующего. Он также включается при написании --help, добавлении подкоманды и проектировании сообщений об ошибках.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →

Сначала — cli-for-agents от других авторов.

cli-for-agents cursor Скилл cli-for-agents помогает проектировать и проверять консольные утилиты, чтобы автономные агенты запускали их без зависаний на интерактивных вопросах. CX Codex +1 1 400установок dart-build-cli-app dart-lang Скилл dart-build-cli-app для разработки command-line приложений на Dart. Даёт паттерны архитектуры, структуру точки входа, коды выхода, маршрутизацию потоков и запуск подпроцессов. CX Codex +1 20 000установок golang-spf13-cobra samber Скилл golang-spf13-cobra для Claude Code по работе с spf13/cobra — библиотекой Go для построения деревьев команд, валидации аргументов, флагов и автодополнения в терминале. Пишет и расширяет CLI-приложения на Go. CX Codex +1 39 300установок mem0-cli mem0ai Скилл mem0-cli помогает агенту работать с памятью Mem0 через терминал: добавлять, искать, просматривать и менять записи. CX Codex +1 836установок console-cli codewithmukesh Скилл console-cli для Claude Code генерирует консольные приложения и CLI-утилиты на .NET 10 с использованием System.CommandLine 2.x. CX Codex +1 750установок create-cli steipete Скилл create-cli помогает спроектировать интерфейс консольной утилиты до написания кода: аргументы, флаги, коды возврата и правила вывода по стандартам clig.dev. CX Codex +1 508установок huawei-cloud-cli-guidance huaweicloud Скилл huawei-cloud-cli-guidance для Claude Code и Codex помогает работать с утилитой KooCLI в Huawei Cloud. Ассистент подсказывает синтаксис hcloud, правила авторизации и шаги разбора ошибок. CX Codex +1 239установок

Из того же набора139

Весь набор →
opencode-ts Скилл opencode-ts помогает писать, проверять и рефакторить TypeScript-код в проектах на Effect. Он задаёт рабочий процесс и сверяет изменения с архитектурой проекта. CX Codex +1 240установок exec-plan Скилл exec-plan организует жизненный цикл автономных планов разработки в Markdown для задач длиннее одной сессии или с правками более трёх файлов. CX Codex +1 239установок graph-schema Скилл graph-schema для Claude Code помогает проектировать, проверять и перерабатывать схемы графовых баз данных. Он включается при моделировании узлов и связей или переносе предметной области в граф. CX Codex +1 239установок clean-code-ts-react Скилл clean-code-ts-react переносит принципы Clean Code Роберта Мартина на TypeScript 5.x и React 19. Помогает на код-ревью, при рефакторинге и проектировании компонентов или функций. CX Codex +1 238установок eval-mcp Скилл eval-mcp проверяет схемы MCP-сервера и точность выбора инструментов моделью. Находит пересечения в описаниях и тестирует вызовы на синтетических запросах. CX Codex +1 234установок threat-patch Скилл threat-patch берёт находки сканера или модель угроз и превращает их в небольшие патчи кода с описанием правок и шагами проверки. CX Codex +1 232установок diagram-quality Скилл diagram-quality задаёт правила отрисовки PlantUML на холсте agent-uml, предотвращая ошибки HTTP 400 и пустые схемы при работе с инструментами дизайна. CX Codex +1 230установок drizzle-sqlite Скилл drizzle-sqlite помогает писать и проверять Drizzle ORM для SQLite: схемы, миграции, запросы, транзакции и типы. Подходит для рефакторинга SQLite-кода. CX Codex +1 221установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой