home / skills / steipete / agent-scripts / create-cli

create-cli skill

This skill designs concise, human-first CLI specs (commands, flags, prompts, and dry-run safety) to maximize discoverability and consistency.

npx playbooks add skill steipete/agent-scripts --skill create-cli

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

3.6 KB

---
name: create-cli
description: >
  Design command-line interface parameters and UX: arguments, flags, subcommands,
  help text, output formats, error messages, exit codes, prompts, config/env
  precedence, and safe/dry-run behavior. Use when you’re designing a CLI spec
  (before implementation) or refactoring an existing CLI’s surface area for
  consistency, composability, and discoverability.
---

# Create CLI

Design CLI surface area (syntax + behavior), human-first, script-friendly.

## Do This First

- Read `agent-scripts/skills/create-cli/references/cli-guidelines.md` and apply it as the default rubric.
- Upstream/full guidelines: https://clig.dev/ (propose changes: https://github.com/cli-guidelines/cli-guidelines)
- Ask only the minimum clarifying questions needed to lock the interface.

## Clarify (fast)

Ask, then proceed with best-guess defaults if user is unsure:

- Command name + one-sentence purpose.
- Primary user: humans, scripts, or both.
- Input sources: args vs stdin; files vs URLs; secrets (never via flags).
- Output contract: human text, `--json`, `--plain`, exit codes.
- Interactivity: prompts allowed? need `--no-input`? confirmations for destructive ops?
- Config model: flags/env/config-file; precedence; XDG vs repo-local.
- Platform/runtime constraints: macOS/Linux/Windows; single binary vs runtime.

## Deliverables (what to output)

When designing a CLI, produce a compact spec the user can implement:

- Command tree + USAGE synopsis.
- Args/flags table (types, defaults, required/optional, examples).
- Subcommand semantics (what each does; idempotence; state changes).
- Output rules: stdout vs stderr; TTY detection; `--json`/`--plain`; `--quiet`/`--verbose`.
- Error + exit code map (top failure modes).
- Safety rules: `--dry-run`, confirmations, `--force`, `--no-input`.
- Config/env rules + precedence (flags > env > project config > user config > system).
- Shell completion story (if relevant): install/discoverability; generation command or bundled scripts.
- 5–10 example invocations (common flows; include piped/stdin examples).

## Default Conventions (unless user says otherwise)

- `-h/--help` always shows help and ignores other args.
- `--version` prints version to stdout.
- Primary data to stdout; diagnostics/errors to stderr.
- Add `--json` for machine output; consider `--plain` for stable line-based text.
- Prompts only when stdin is a TTY; `--no-input` disables prompts.
- Destructive operations: interactive confirmation + non-interactive requires `--force` or explicit `--confirm=...`.
- Respect `NO_COLOR`, `TERM=dumb`; provide `--no-color`.
- Handle Ctrl-C: exit fast; bounded cleanup; be crash-only when possible.

## Templates (copy into your answer)

### CLI spec skeleton

Fill these sections, drop anything irrelevant:

1. **Name**: `mycmd`
2. **One-liner**: `...`
3. **USAGE**:
   - `mycmd [global flags] <subcommand> [args]`
4. **Subcommands**:
   - `mycmd init ...`
   - `mycmd run ...`
5. **Global flags**:
   - `-h, --help`
   - `--version`
   - `-q, --quiet` / `-v, --verbose` (define exactly)
   - `--json` / `--plain` (if applicable)
6. **I/O contract**:
   - stdout:
   - stderr:
7. **Exit codes**:
   - `0` success
   - `1` generic failure
   - `2` invalid usage (parse/validation)
   - (add command-specific codes only when actually useful)
8. **Env/config**:
   - env vars:
   - config file path + precedence:
9. **Examples**:
   - …

## Notes

- Prefer recommending a parsing library (language-specific) only when asked; otherwise keep this skill language-agnostic.
- If the request is “design parameters”, do not drift into implementation.

Overview

This skill designs a clear, script-friendly command-line interface surface: arguments, flags, subcommands, help text, output formats, error codes, prompts, and config precedence. It produces a compact, implementable CLI spec (command tree, usage, flags, I/O contract, exit codes, safety rules, examples) you can hand to a developer before implementation.

How this skill works

I ask the minimum clarifying questions (command name, primary user, input sources, output contract, interactivity, config model, platform constraints) and then produce a default-first spec if you’re unsure. The output is a filled CLI spec skeleton: USAGE, subcommands, args/flags table, I/O/exit-code rules, config precedence, safety behavior, completion story, and example invocations.

When to use it

Designing a new CLI interface before coding an implementation.
Refactoring an existing CLI for consistency and discoverability.
Defining machine-friendly output and error contracts for scripting.
Adding safe/dry-run, confirmation, or config precedence rules.
Preparing documentation or acceptance criteria for implementers.

Best practices

Start with a one-line command purpose and primary user (human, script, or both).
Prefer human-first help with a stable --json and optional --plain for scripts.
Make prompts conditional on TTY; require --no-input/--force for non-interactive runs.
Keep stdout for primary data, stderr for diagnostics; respect NO_COLOR/TERM and provide --no-color.
Define a small, meaningful exit code set and document top failure modes.
Provide 5–10 example invocations including piped/stdin and --dry-run scenarios.

Example use cases

Design a new deploy command set with init/plan/apply and a safe --dry-run mode.
Refactor a repo tool to add consistent global flags (--json, --quiet, --verbose) and config precedence.
Create a small utility that accepts data via file, URL, or stdin and exposes stable machine output.
Specify destructive operations to require interactive confirmation or explicit --confirm token.
Define shell completion generation and installation instructions for a single-binary tool.

FAQ

What minimal questions will you ask before producing a spec?

Command name and one-line purpose, primary user (human/script), input sources, output contract, interactivity rules, config model, and platform/runtime constraints.

Do you produce implementation code?

No — I deliver a language-agnostic, implementable CLI spec (usage, flags, I/O, exit codes, examples) rather than parser code.

How do you handle destructive operations?

Recommend interactive confirmation by default; non-interactive requires --force or explicit --confirm=TOKEN and provide --dry-run for safe previews.