Skip to content

Instantly share code, notes, and snippets.

@imaurer

imaurer/create-cli-skill.md

Created December 31, 2025 20:00
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save imaurer/6f282b37ebbc85f6144b818f823c42a6 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save imaurer/6f282b37ebbc85f6144b818f823c42a6 to your computer and use it in GitHub Desktop.
Download ZIP
Use https://clig.dev/ to improve @steipete’s CLI skill prompt
Raw
create-cli-skill.md

prompt chatgpt 5.2 pro (12/31/2025)

How would you improve the prompt based on the below document? Be explicit, provide detailed analysis of what's missing, what could be better, what would be tweaked. And then after all your analysis and bullet points, give me the new prompt.

original skill

https://github.com/steipete/agent-scripts/blob/main/skills/create-cli/SKILL.md

document

https://clig.dev

What your current prompt already does well (relative to clig.dev)

Your “Create CLI” prompt is already aligned with several of the “Basics” and core interaction conventions in the CLI Guidelines:

  • Clear scope: it focuses on surface area (syntax + behavior) rather than implementation.
  • Human-first + script-friendly framing: matches the guide’s emphasis on balancing usability and composability.
  • Good default contracts: -h/--help, --version, stdout vs stderr separation, --json/--plain, TTY-gated prompts, --no-input, destructive confirmation, NO_COLOR/TERM=dumb, Ctrl-C behavior, and config precedence are all directionally consistent with the guide. oai_citation:0‡clig.dev

That said, clig.dev is extremely specific about the parts that make CLIs “discoverable,” “conversational,” and “robust.” Your prompt touches those topics, but doesn’t force the designer to specify them. The improvements below make those expectations explicit.

What’s missing or under-specified (and what I would add)

1) Help UX needs explicit “concise-by-default” behavior

clig.dev draws a strong distinction between:

  • Full help when asked (-h/--help, and also myapp help … for git-like tools).
  • Concise help by default when the command requires arguments but is invoked without them.

Your prompt currently says “-h/--help always shows help,” but it does not require:

  • a concise help page on empty invocation (one-liner + 1–2 examples + “run --help”)
  • “help ignores other args” behavior (append -h to anything)
  • help formatting guidance (headings, scan-ability)
  • including support links and docs links in help

These are all explicitly recommended. oai_citation:1‡clig.dev

Tweaks to make:

  • Add a “Help contract” section to deliverables.
  • Add defaults: “empty invocation prints concise help unless interactive-by-default tool.”
  • Require help to lead with examples, include a support path, and link to web docs. oai_citation:2‡clig.dev

2) Add “suggestions” and “conversational” error recovery to the spec

clig.dev strongly recommends:

  • If the user did something wrong and you can guess what they meant, suggest it (optionally prompt), but don’t silently do it. oai_citation:3‡clig.dev
  • If the command expects piped input but stdin is a TTY, don’t hang—print help/log message and quit. oai_citation:4‡clig.dev

Your prompt currently doesn’t require either behavior.

Tweaks to make:

  • Add a deliverable for “typo recovery/suggestions” (including safety rules: never auto-run suggestions if state-changing).
  • Add a default rule for piped-input expectations: detect missing stdin and exit with a helpful message. oai_citation:5‡clig.dev

3) Documentation is absent (help ≠ docs)

clig.dev treats help as quick orientation, but expects actual documentation channels too:

  • web docs (searchable, linkable)
  • terminal docs, optionally man pages
  • “help subcommand” parity with man pages for git-like tools oai_citation:6‡clig.dev

Your prompt talks about help text, but not doc strategy.

Tweaks to make:

  • Add “Documentation” as a deliverable: web docs link targets + terminal docs shape (help subcommand, man pages, etc.). oai_citation:7‡clig.dev

4) Output rules need more nuance: pager, animations, “don’t log to stderr,” and TTY-specific formatting

You already mention --json and --plain and TTY detection. What’s missing is the practical detail clig.dev calls out:

Your prompt mentions stdout/stderr split, but does not mandate these interaction details.

Tweaks to make:

  • Add explicit deliverables for pager policy, animation policy, verbosity policy, and stderr “signal-to-noise” expectations.
  • Add a default: “no progress spinners/progress bars on non-TTY stdout.” oai_citation:14‡clig.dev

5) Error UX should be specified as “human rewritten,” grouped, and with a bug-report path

clig.dev is very explicit about errors:

  • Catch and rewrite errors for humans
  • Optimize signal/noise; group repetitive errors
  • Put the most important info at the end
  • On unexpected errors: provide debug/traceback and bug submission instructions; consider writing debug logs to a file
  • Make bug reports effortless (pre-populated URL) oai_citation:15‡clig.dev

Your prompt asks for “error messages” and “exit codes” but not the design of error UX.

Tweaks to make:

  • Add an “Error UX spec” deliverable: canonical format, remediation hints, “what to run next,” debug mode behavior, bug-report link strategy, and exit-code mapping. oai_citation:16‡clig.dev

6) Security guidance should explicitly include “no secrets in env vars,” not only “no secrets via flags”

Your clarify section says “secrets (never via flags).” clig.dev goes further:

Tweaks to make:

  • Update the prompt to explicitly forbid secrets via flags and env vars, and to require an approved secret-input mechanism. oai_citation:19‡clig.dev

7) Arguments/flags design guidance needs “prefer flags,” “standard names,” “- for stdin/stdout,” and “order independence”

Your prompt asks for args/flags and has defaults, but it doesn’t require several high-leverage conventions:

Tweaks to make:

  • Add these as explicit default conventions and as validation checks in the deliverables.

8) Config/env should specify “XDG, precedence, general env vars, and .env limits”

You already list precedence and mention XDG vs repo-local, but clig.dev provides concrete expectations:

  • Precedence order: flags > env > project-level (.env) > user-level > system-wide oai_citation:26‡clig.dev
  • Follow XDG base dirs for user config locations oai_citation:27‡clig.dev
  • Env var naming constraints (uppercase/underscores), and common env vars to respect (NO_COLOR, FORCE_COLOR, DEBUG, EDITOR, proxies, PAGER, etc.) oai_citation:28‡clig.dev
  • .env is useful in some cases, but not a substitute for a real config file; and it often contains secrets (which shouldn’t be read from env vars anyway) oai_citation:29‡clig.dev

Tweaks to make:

9) Future-proofing rules should be baked into the prompt

Your prompt is silent on a major clig.dev theme: interface stability.

Key future-proofing guidance:

  • Keep changes additive where possible; warn before non-additive changes
  • Encourage --plain/--json for script stability
  • Don’t implement a “catch-all subcommand” parser that treats unknown subcommands as a default action
  • Don’t allow arbitrary subcommand abbreviations; aliases must be explicit and stable oai_citation:31‡clig.dev

Tweaks to make:

  • Add a “Future-proofing” deliverable section requiring an explicit alias/deprecation policy and prohibiting catch-all parsing and implicit abbreviations. oai_citation:32‡clig.dev

10) Robustness/perceived robustness: responsiveness, progress, timeouts, Ctrl‑C semantics

You mention Ctrl-C and crash-only, which is good. clig.dev adds actionable robustness details:

  • Be responsive; show progress for long operations
  • Don’t show animations when stdout isn’t TTY
  • Make operations recoverable and idempotent where possible
  • Ctrl-C should exit quickly; cleanup bounded; second Ctrl-C can force exit oai_citation:33‡clig.dev

Tweaks to make:

The improved prompt

---
name: create-cli
description: >
  Design command-line interface parameters and UX: command tree, arguments, flags,
  help + docs UX, stdout/stderr contracts, output formats, error messages,
  exit codes, interactivity, safety/dry-run behavior, config/env precedence,
  and interface future-proofing. Use for new CLI specs or refactors.
---

# Create CLI

Design a CLI surface area (syntax + behavior) that is human-first, script-friendly,
composable, consistent with established CLI conventions, and robust under misuse.

## Default rubric

- Apply `agent-scripts/skills/create-cli/references/cli-guidelines.md`.
- Additionally apply the Command Line Interface Guidelines (clig.dev) as the
  default rubric, especially for: help/discovery, stdout/stderr separation,
  TTY-aware output, errors-as-documentation, config/env precedence, and
  future-proofing (no catch-all parsing, no implicit abbreviations).

## Clarify (fast)

Ask only the minimum questions needed to lock the interface; otherwise assume
sensible defaults.

1) **Identity**
- Command name (lowercase, memorable) + one-sentence purpose.
- Primary user: humans, scripts, or both (state which is primary).

2) **Inputs**
- Primary inputs: flags/args vs stdin.
- File/URL inputs: required? optional? support `-` for stdin/stdout?
- Secrets: confirm secret inputs will NOT be accepted via flags or env vars; choose
  a safe mechanism (stdin, `--*-file`, OS keychain/secret manager, etc.).

3) **Outputs**
- Primary output entities (what is “data”) vs diagnostics.
- Required machine output: `--json`? required stable line-based `--plain`?
- Does output get long? need pager behavior (TTY-only; respects `PAGER`)?
- Long-running operations: progress indicator? timeouts? retries?

4) **Interactivity**
- Prompts allowed only when stdin is a TTY.
- Need `--no-input` for CI?
- Destructive/irreversible actions: confirmation model (`--force`, `--confirm=…`,
  typed confirmations for severe ops).

5) **Config/env**
- Config sources: flags, env vars, project config, user config, system config.
- Precedence (default: flags > env > project > user > system).
- Config locations (default: XDG for user config); any repo-local config?
- Which common env vars should be honored (NO_COLOR/FORCE_COLOR, DEBUG, EDITOR,
  proxies, PAGER, etc.)?

6) **Compatibility & evolution**
- Backward-compat expectations (semver, deprecation policy).
- Alias policy: explicit/stable aliases only; no arbitrary abbreviations.
- “Unknown subcommand” behavior (default: error; no catch-all).

## Deliverables

Produce a compact spec that can be implemented without additional design work:

1) **Command tree + synopsis**
- Top-level usage and subcommand list (grouped by workflows where helpful).
- For each subcommand: purpose, inputs, side effects, idempotence, and state changes.

2) **Help UX spec**
- Full help (`-h/--help`) for command + subcommands.
- Concise help when required args are missing (one-liner + 1–2 examples + “run --help”).
- Help formatting (USAGE/OPTIONS/COMMANDS/EXAMPLES headings).
- Include: support path (issues/feedback) + link targets to web docs.
- If the CLI expects piped input but stdin is a TTY, print a helpful message/help and exit.

3) **Args/flags table**
For every flag/arg include:
- name(s) (short only if truly common), type, default, required/optional
- examples
- env var mapping (if any) + security notes
- whether it is stable for scripts / included in `--json`/`--plain` output contracts

4) **I/O & output contract**
- stdout: primary data only (including machine-readable output).
- stderr: errors/diagnostics only (keep high signal-to-noise; no log-level labels by default).
- TTY behavior:
  - human-readable formatting when TTY
  - `--plain` for stable line-based output when human formatting would break composability
  - `--json` for structured output
  - disable color if not TTY, NO_COLOR set, TERM=dumb, or `--no-color`
  - disable animations/progress spinners when stdout is not TTY
  - pager policy for long output (TTY-only; respects `PAGER`)
- Quiet/verbose/debug semantics (`-q/--quiet`, `-v/--verbose`, optional `--debug`).

5) **Errors + exit codes**
- Canonical error message style (human-readable cause + remediation + “what to run next”).
- Suggest corrections for likely typos/misuse, without auto-running state-changing actions.
- Debug/traceback strategy for unexpected errors (optionally write debug logs to a file).
- Bug-report path (URL or instructions) suitable for copy/paste.
- Exit code map:
  - 0 success
  - 1 runtime failure
  - 2 invalid usage/validation
  - 130 for SIGINT (Ctrl-C), if applicable
  - add more only when they encode meaningful, stable categories.

6) **Safety rules**
- `--dry-run` behavior (describes changes without applying them).
- Confirmation tiers:
  - mild: may confirm
  - moderate: confirm or require `--force`
  - severe: typed confirmation or `--confirm="<resource-name>"`
- `--no-input` disables all prompts; if required input missing, fail with actionable guidance.

7) **Config/env rules**
- Precedence: flags > env > project config (.env only when appropriate) > user > system.
- XDG default locations for user config; explicit project config file naming if needed.
- Env var naming conventions (uppercase, underscores).
- Do not read secrets from env vars; do not accept secrets via flags.

8) **Future-proofing**
- No catch-all subcommand behavior.
- No implicit or arbitrary subcommand abbreviations.
- Explicit alias list only (stable forever).
- Deprecation strategy for any breaking changes (warnings + migration path).
- Encourage scripts to use `--json` or `--plain` for stability.

9) **Examples**
Provide 5–10 example invocations covering:
- common human workflows
- CI/non-interactive usage (`--no-input`, `--json`, `--plain`, `-q`)
- piping/`-` stdin/stdout examples
- dry-run + confirmation flows

## Default conventions (unless user overrides)

- `-h/--help` always shows help and ignores other args.
- `--version` prints version to stdout.
- stdout is for primary data; stderr is for diagnostics and errors.
- Provide `--json` for structured output; provide `--plain` for stable line-based output.
- Provide `-q/--quiet` to suppress non-essential output; `-v/--verbose` for more context.
- Prompts only when stdin is a TTY; `--no-input` disables prompts.
- Destructive ops: interactive confirmation; non-interactive requires `--force` or explicit `--confirm=...`.
- Respect NO_COLOR, TERM=dumb; add `--no-color`; optionally honor FORCE_COLOR.
- If stdout is not a TTY: no animations/spinners/progress “noise.”
- Use a pager for long TTY output only; respect `PAGER`.
- Ctrl-C exits quickly; cleanup is bounded; second Ctrl-C can force immediate stop.

If you want, I can also provide a compact “diff” (old prompt → new prompt) so you can review the changes mechanically, but the block above is ready to drop in as a replacement.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment