hci-cli-ux
Designs and reviews the user experience of command-line tools. Use whenever the user builds or improves a CLI, script with options, or terminal tool and cares about help text, flags and subcommands, error messages, exit codes, progress output, colors, prompts and confirmations, J
Install
npx skills add https://github.com/MehranQadirian/skills/tree/main/hci/hci-cli-ux
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install mehranqadirian-skills@llmmart
git clone https://github.com/MehranQadirian/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole mehranqadirian/skills collection as a plugin from our marketplace. Git is the plain clone.
README
hci-cli-ux
A Claude skill that applies HCI principles to command-line tools: help, flags, errors, output, safety and scripting.
What it does
- Tests a real command with
check_cli_ux.py: help and usage, examples, exit codes, bad option handling, stderr use, ANSI codes when piped, stdin behavior and--version - Guides naming, help text structure, output design, error wording, prompts, configuration precedence and accessibility
- Rewrites unclear help and error messages
- Explains each rule by the principle behind it
Try it
Review my CLI's help text and error messages.
My tool prints colors and spinners into files when I pipe it. Fix that.
What flags and exit codes should my backup script have?
Install
Claude.ai: zip this folder, then go to Settings > Capabilities > Skills > Upload.
Claude Code:
cp -r hci/hci-cli-ux ~/.claude/skills/
Structure
hci-cli-ux/
├── SKILL.md skill instructions for Claude
├── scripts/check_cli_ux.py CLI experience checker
└── references/cli-guidelines.md guidelines
Skill manifest
hci-cli-ux
A command-line tool is a user interface for people and for other programs. This skill applies HCI principles to it: clear help, predictable flags, human errors, safe actions and machine-friendly output.
hci-cli-ux/
├── SKILL.md
├── scripts/
│ └── check_cli_ux.py runs --help, --version, a bad option and no arguments; checks the experience
└── references/
└── cli-guidelines.md names, help, output, errors, interactivity, config, accessibility, testing
When to use
- Designing a new tool, subcommands or flags
- Improving help text and error messages
- A tool is confusing for beginners or awkward in pipelines and scripts
- Adding progress, colors, prompts, confirmation,
--dry-runor--json - Reviewing exit codes and stdout versus stderr behavior
Workflow
- Understand the users and uses: who runs it (beginner, expert, other programs), how often, interactively or in scripts, on which OS.
- Test the real tool if it exists:
python3 scripts/check_cli_ux.py -- ./tool(add fixed arguments after the command, for example-- python3 tool.py). It runs the tool only with--help,--version, an invalid option and no arguments, with stdin closed and output piped, then reports missing usage and examples, wrong exit codes, errors on stdout, color codes when piped, hanging behavior and absent--version. Run it only on tools you trust. Add--strictto fail on warnings. - Read the help as a newcomer: is the first line clear, are examples present and copyable, are common options first?
- Review errors: each says what happened, why if known, and the next step, on stderr with a non-zero exit code. Rewrite the worst ones using the pattern in the reference.
- Check output design: results on stdout, messages on stderr, no color or spinners when piped,
--jsonwith a stable schema, progress for long work,NO_COLORhonored. - Check safety:
--dry-run, named confirmations for destructive actions,--yesfor scripts, no secrets in arguments, clean Ctrl+C. - Map to principles: visibility of status (progress, summaries), error prevention (dry run, confirmation), recognition over recall (examples, suggestions for typos), consistency (standard flag names), flexibility (short flags, config precedence).
- Report findings, rewritten help and error messages, and what to test by hand with a new user.
Rules
- Results to stdout, diagnostics to stderr, errors exit non-zero, usage errors exit 2
--helpalways works, prints to stdout and exits 0;--versionexists- Never use color or progress animation when output is not a terminal; honor
NO_COLOR - Error messages are human sentences with a next step; stack traces only behind
--debug - Safe by default: destructive actions need an explicit flag or confirmation, and
--dry-runpreviews them - Use standard flag names and keep them consistent across subcommands
- Never read secrets from command-line arguments
- Do not run unknown commands to test them; only run tools the user trusts
What to report back
| Field | Content |
|---|---|
| Script results | findings with severity |
| Help review | clarity, examples, order, wording |
| Error review | rewritten messages with exit codes |
| Output and safety | stdout and stderr use, machine output, dry run, confirmations |
| Manual tests left | pipe test, no-color test, beginner run, Windows and Termux behavior |
Related skills
shell-scripting: write safe shell tools with strict mode and dry runhci-microcopy: wording of messages, errors and promptshci-foundations: principles and evaluation reportshci-desktop-apps: graphical desktop software
Files (skills)
-
references
-
cli-guidelines.md 5.1 KB
Loading…
-
-
scripts
-
check_cli_ux.py 5.6 KB
Loading…
-
-
README.md 1.1 KB
# hci-cli-ux A [Claude skill](../../README.md) that applies HCI principles to command-line tools: help, flags, errors, output, safety and scripting. ## What it does - Tests a real command with `check_cli_ux.py`: help and usage, examples, exit codes, bad option handling, stderr use, ANSI codes when piped, stdin behavior and `--version` - Guides naming, help text structure, output design, error wording, prompts, configuration precedence and accessibility - Rewrites unclear help and error messages - Explains each rule by the principle behind it ## Try it > Review my CLI's help text and error messages. > My tool prints colors and spinners into files when I pipe it. Fix that. > What flags and exit codes should my backup script have? ## Install **Claude.ai:** zip this folder, then go to Settings > Capabilities > Skills > Upload. **Claude Code:** ```bash cp -r hci/hci-cli-ux ~/.claude/skills/ ``` ## Structure ``` hci-cli-ux/ ├── SKILL.md skill instructions for Claude ├── scripts/check_cli_ux.py CLI experience checker └── references/cli-guidelines.md guidelines ``` -
SKILL.md 4.2 KB
--- name: hci-cli-ux description: Designs and reviews the user experience of command-line tools. Use whenever the user builds or improves a CLI, script with options, or terminal tool and cares about help text, flags and subcommands, error messages, exit codes, progress output, colors, prompts and confirmations, JSON output, piping, or beginner friendliness, even if they only say "my script is hard to use". Tests a real command with a script that checks help, bad options, version, ANSI codes and stdin behavior. --- # hci-cli-ux A command-line tool is a user interface for people and for other programs. This skill applies HCI principles to it: clear help, predictable flags, human errors, safe actions and machine-friendly output. ``` hci-cli-ux/ ├── SKILL.md ├── scripts/ │ └── check_cli_ux.py runs --help, --version, a bad option and no arguments; checks the experience └── references/ └── cli-guidelines.md names, help, output, errors, interactivity, config, accessibility, testing ``` ## When to use - Designing a new tool, subcommands or flags - Improving help text and error messages - A tool is confusing for beginners or awkward in pipelines and scripts - Adding progress, colors, prompts, confirmation, `--dry-run` or `--json` - Reviewing exit codes and stdout versus stderr behavior ## Workflow 1. **Understand the users and uses**: who runs it (beginner, expert, other programs), how often, interactively or in scripts, on which OS. 2. **Test the real tool** if it exists: `python3 scripts/check_cli_ux.py -- ./tool` (add fixed arguments after the command, for example `-- python3 tool.py`). It runs the tool only with `--help`, `--version`, an invalid option and no arguments, with stdin closed and output piped, then reports missing usage and examples, wrong exit codes, errors on stdout, color codes when piped, hanging behavior and absent `--version`. Run it only on tools you trust. Add `--strict` to fail on warnings. 3. **Read the help as a newcomer**: is the first line clear, are examples present and copyable, are common options first? 4. **Review errors**: each says what happened, why if known, and the next step, on stderr with a non-zero exit code. Rewrite the worst ones using the pattern in the reference. 5. **Check output design**: results on stdout, messages on stderr, no color or spinners when piped, `--json` with a stable schema, progress for long work, `NO_COLOR` honored. 6. **Check safety**: `--dry-run`, named confirmations for destructive actions, `--yes` for scripts, no secrets in arguments, clean Ctrl+C. 7. **Map to principles**: visibility of status (progress, summaries), error prevention (dry run, confirmation), recognition over recall (examples, suggestions for typos), consistency (standard flag names), flexibility (short flags, config precedence). 8. **Report** findings, rewritten help and error messages, and what to test by hand with a new user. ## Rules - Results to stdout, diagnostics to stderr, errors exit non-zero, usage errors exit 2 - `--help` always works, prints to stdout and exits 0; `--version` exists - Never use color or progress animation when output is not a terminal; honor `NO_COLOR` - Error messages are human sentences with a next step; stack traces only behind `--debug` - Safe by default: destructive actions need an explicit flag or confirmation, and `--dry-run` previews them - Use standard flag names and keep them consistent across subcommands - Never read secrets from command-line arguments - Do not run unknown commands to test them; only run tools the user trusts ## What to report back | Field | Content | |-------|---------| | Script results | findings with severity | | Help review | clarity, examples, order, wording | | Error review | rewritten messages with exit codes | | Output and safety | stdout and stderr use, machine output, dry run, confirmations | | Manual tests left | pipe test, no-color test, beginner run, Windows and Termux behavior | ## Related skills - `shell-scripting`: write safe shell tools with strict mode and dry run - `hci-microcopy`: wording of messages, errors and prompts - `hci-foundations`: principles and evaluation reports - `hci-desktop-apps`: graphical desktop software
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.