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:
Name
:
mycmd
One-liner
:
...
USAGE
:
mycmd [global flags]
creating-cli-tools
安装
npx skills add https://github.com/zenobi-us/dotfiles --skill creating-cli-tools