Create Cli

---

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] [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.

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.