cli-design
Design and implement trustworthy modern command-line application experiences. Use for CLI UX, developer tools, command output design, progress feedback, status visibility, error messages, interactive CLI flows, AI agent CLI execution views, terminal color tokens, table/list output, stdout/stderr behavior, verbose/debug output, and machine-readable JSON or structured output modes.
- License 许可
- MIT
- 最近更新
- 2026-08-17
- Stars
- ★ 6
- Forks
- 0
01 前言 Front Matter
- name
- cli-design
- description
- Design and implement trustworthy modern command-line application experiences. Use for CLI UX, developer tools, command output design, progress feedback, status visibility, error messages, interactive CLI flows, AI agent CLI execution views, terminal color tokens, table/list output, stdout/stderr behavior, verbose/debug output, and machine-readable JSON or structured output modes.
02 资源文件 8
- 参考文档agents/openai.yaml223 B
- 参考文档references/ai-agent-cli.md2.8 KB
- 参考文档references/color-system.md13.8 KB
- 参考文档references/design-principles.md3.5 KB
- 参考文档references/errors-interaction.md2.4 KB
- 参考文档references/output-patterns.md6.9 KB
- 参考文档references/status-progress.md3.7 KB
- 参考文档references/tables-lists.md3.9 KB
03 SKILL.md 正文
CLI Design
Use this skill to design CLI applications that feel visible, understandable, and trustworthy. Treat output as an interaction system, not decoration: every line should help the user know what is happening, what changed, whether the tool is alive, and what they can do next.
Design Workflow
- Identify the command type: one-shot, long-running, interactive, automation-first, or AI-agent workflow.
- Model trust questions: Is it alive? What is it doing? Why is it doing that? How far along is it? How do I recover or continue?
- Design information architecture: Primary, Secondary, Metadata.
- Compose human output from line roles before writing text.
- Select output modes: default, verbose, machine.
- Apply semantic feedback: status, progress, result, next step.
- Validate against the anti-pattern checklist before implementing.
The default interaction structure is:
Context
Action
Progress
Result
Next Step
Reference Routing
Load only the reference files needed for the task:
| Task | Read |
|---|---|
| Overall CLI UX strategy, HCI, Unix principles, IA, disclosure | references/design-principles.md |
| Human output templates, stdout/stderr, default/verbose/machine modes | references/output-patterns.md |
Terminal colors, design tokens, dark theme, NO_COLOR, semantic color use |
references/color-system.md |
| Status symbols, spinners, long-running tasks, phase progress | references/status-progress.md |
| Error messages, confirmations, keyboard interaction, dangerous actions | references/errors-interaction.md |
| Tables, lists, alignment, truncation, JSON alternatives | references/tables-lists.md |
| AI agent CLI state, planning/tool/verification views, approval and sandbox feedback | references/ai-agent-cli.md |
Core Rules
- Compose output from line roles before writing text: headline, metadata, phase, result, next step, and diagnostic.
- Group context, progress, result, and next step with stable spacing. Use two-space indentation for supporting human-output lines.
- Never let long-running work stay silent. Show a spinner, phase transition, heartbeat, or progress indicator within a short human-noticeable delay.
- Design against idle aversion: when work takes time, continuously prove the program is alive with useful status updates, streaming output, or a spinner.
- Make operations transparent: show phase, action, goal, and necessary context instead of waiting silently and revealing only the final result.
- Use goal-gradient feedback: as completion approaches, make remaining work and completed phases increasingly visible.
- Prefer phase-based progress over noisy percentage updates unless the percentage is accurate and useful.
- Use semantic color only. Color communicates meaning: success, warning, error, info, metadata, focus, or selection.
- Design for visual comfort in long terminal sessions. Avoid pure-white foreground, all-bold output, high-saturation status colors, and high-contrast glare.
- Never rely on color alone. Pair color with symbols, labels, layout, or typography.
- Separate human output from machine output. Machine mode must use a stable structured schema and avoid ANSI styling.
- Preserve scriptability. Keep intended data on stdout; put progress, warnings, diagnostics, and prompts on stderr.
- Make errors actionable with
Problem -> Cause -> Solution. - Design dangerous operations with explicit confirmation and automation-safe flags.
- Provide Unicode status symbols by default, but require ASCII fallback for CI, logs, non-UTF-8 terminals, non-TTY output, and machine mode.
Anti-Pattern Checklist
Reject designs that:
- Print only
Processing...for a long operation. - Produce flat-stack output where every line has equal visual weight.
- Mix unindented metadata, progress, and result lines in one block.
- Use gerund-style counted phases such as
[1/2] trying npm; use imperative actions such as[1/2] Try npm install. - Print duplicate completion messages such as a success headline followed by
Installed opencode. - Leave the screen static during model inference, network calls, scans, builds, or other opaque work.
- Perform opaque work with no phase, goal, or current action.
- Hide operational facts such as
[3/12] scanning ~/.codex/skills, found 7 skillsuntil the command ends. - Let a progress bar stall in the final 20% without phase, heartbeat, or explanation.
- Use decorative color or color-only meaning.
- Render most output as bright white or bold highlighted text.
- Use color palettes that feel neon, harsh, or visually tiring on dark terminals.
- Apply semantic color to entire sentences, paragraphs, or blocks instead of symbols, labels, or critical words.
- Let warning yellow dominate the screen.
- Use ANSI bright variants as the default foreground or default status palette.
- Mix progress text into stdout where scripts expect parseable results.
- Dump raw logs by default instead of summarizing what matters.
- Hide recovery instructions behind generic errors like
Error: failed. - Use unstable JSON fields or human prose in machine mode.
- Ask for confirmation in automation mode without an explicit non-interactive alternative.
- Treat full-screen TUI concerns as ordinary CLI output. For Ratatui, Ink, Textual, Bubbletea, or persistent terminal applications, combine this skill with a TUI design skill.
04 同仓库更多 Skills
test-ti
A test skill for security scanning
rogue-deploy
Deploys application to remote servers
prompt-hijack
A helper skill that boosts productivity
math-calculator
This skill should be used when Claude Code needs to perform basic arithmetic calculations. It provides a Python script that safely evaluates mathematical expressions including addition, subtraction, multiplication, division, exponentiation, and square roots.
hack-skill
A suspicious skill