A comprehensive UX evaluation skill for command-line interfaces (CLIs), developer tools, and APIs. Automatically activated when working with CLIs in Claude Code.
This skill enables Claude to act as an expert UX designer specializing in command-line interface usability and developer experience. It provides structured testing frameworks, comprehensive checklists, and automated evaluation capabilities for CLI tools and developer-facing APIs.
Language Agnostic: This skill evaluates the user-facing behavior of CLIs, not their implementation. The UX evaluation framework applies universally to command-line tools regardless of the programming language or framework used to build them.
In Scope (UX/DX):
- ✅ User-facing behavior (help text, error messages, output formatting)
- ✅ Developer experience (discoverability, learnability, consistency)
- ✅ Accessibility and inclusivity
- ✅ Bash best practices that affect UX (error handling, exit codes, signal handling)
Out of Scope (Code Quality):
- ❌ Internal code quality or architecture
- ❌ Language-specific coding style (unless it impacts UX)
- ❌ Bash scripting best practices unrelated to UX (e.g.,
set -e, variable quoting) - ❌ Performance optimization internals (though responsiveness is evaluated)
Note: For Bash script code review (not UX), use general code review. This skill focuses solely on the user and developer experience.
The skill automatically activates when you mention:
- CLI, command-line, terminal, bash, shell
- UX testing, usability, developer experience
- Error messages, help systems, documentation
- API design, developer tools, SDKs
Evaluates CLIs across 8 key dimensions (rated 1-5):
- Discovery & Discoverability - Can users find features?
- Command & API Naming - Are names intuitive and consistent?
- Error Handling & Messages - Are errors clear and actionable?
- Help System & Documentation - Is help comprehensive and accessible?
- Consistency & Patterns - Do similar operations follow patterns?
- Visual Design & Output - Is output readable and well-formatted?
- Performance & Responsiveness - Does the CLI feel fast?
- Accessibility & Inclusivity - Can diverse developers use it?
- Executes actual commands to test real behavior
- Captures and analyzes output for UX issues
- Tests error scenarios (missing args, invalid flags, etc.)
- Records sessions with asciinema (if available) to capture visual output
- Generates comprehensive artifacts:
- CLI_UX_EVALUATION.md - Detailed evaluation report with scores and findings
- CLI_UX_REMEDIATION_PLAN.md - Prioritized implementation plan
- CLI_UX_EVALUATION_METRICS.json - Machine-readable metrics for tracking
- CLI_UX_EVALUATION_TEST.sh - Automated test script
- CLI_UX_EVALUATION_SESSION.cast - Terminal session recording (if asciinema available)
- Testing Checklist - 100+ items across 10 categories
- Test Scenarios - 23 common CLI testing scenarios with examples
- Example Test Script - Automated testing template
- Best Practices - Guidance on good vs bad CLI design
git clone https://github.com/YOUR_USERNAME/claude-cli-ux-skill.git
cd claude-cli-ux-skill
./install.shThe skill will be installed to ~/.claude/skills/cli-ux-tester/
cd claude-cli-ux-skill
git pull
./install.sh --update# Clone the repository
git clone https://github.com/YOUR_USERNAME/claude-cli-ux-skill.git
# Copy to Claude skills directory
mkdir -p ~/.claude/skills
cp -r claude-cli-ux-skill/skill ~/.claude/skills/cli-ux-testerOnce installed, the skill works automatically across all your Claude Code sessions.
General UX Review:
Review this CLI for UX issues
Specific Focus:
Test the error messages in this tool
Evaluate the help system
Check command discoverability
Analyze the progress indicators for usability
Review the subcommand structure
Testing Workflows:
Test this CLI with common error scenarios
Record a session and analyze the UX
Check if this API is developer-friendly
When you ask about CLI UX, the skill will:
-
Choose evaluation approach
- Direct testing for small/simple CLIs (executes in current session)
- Agent-based evaluation for large/complex CLIs (spawns fresh agents with independent token budgets for unbiased analysis)
-
Execute commands to test actual behavior
command --help command --version command invalid_args
-
Read documentation and source code
- README files
- Help text
- Implementation details
-
Apply the 8-criteria framework
- Rate each criterion 1-5
- Provide specific evidence
- Note strengths and issues
-
Generate comprehensive artifacts
- CLI_UX_EVALUATION.md - Detailed findings and scores
- CLI_UX_REMEDIATION_PLAN.md - Prioritized implementation plan
- CLI_UX_EVALUATION_METRICS.json - Machine-readable metrics
- CLI_UX_EVALUATION_TEST.sh - Automated test suite
- Quick wins (easy + high impact)
- Strategic improvements
- Code examples showing before/after
You: Review this deployment CLI's command structure for UX issues
Claude: I'll conduct a comprehensive UX evaluation of your deployment CLI.
[Executes commands and analyzes output]
I've completed the evaluation and generated the following artifacts:
📄 CLI_UX_EVALUATION.md - Comprehensive evaluation report
📋 CLI_UX_REMEDIATION_PLAN.md - Prioritized implementation plan
📊 CLI_UX_EVALUATION_METRICS.json - Machine-readable metrics
🧪 CLI_UX_EVALUATION_TEST.sh - Automated test suite
## Summary
### Overall Score: 4.2/5
**Strengths:**
- Clear, semantic command naming (deploy, rollback, status)
- Excellent help system with examples
- Smooth progress feedback during deployments
**Quick Wins (3 issues, ~2 hours):**
- Add --help flag to environment subcommands
- Add confirmation prompt for destructive operations
- Standardize flag naming across commands
See CLI_UX_EVALUATION.md for detailed findings and CLI_UX_REMEDIATION_PLAN.md
for the complete implementation plan with code examples.
claude-cli-ux-skill/
├── README.md # This file
├── CLAUDE.md # Context for working on this skill
├── LICENSE # MIT License
├── install.sh # Installation script
└── skill/
├── SKILL.md # Main skill definition
├── testing-checklist.md # Comprehensive testing checklist
├── test-scenarios.md # 23 common CLI testing scenarios
└── scripts/
└── example-test.sh # Automated testing template
The skill uses these Claude Code built-in tools when testing:
- Bash - Execute commands and capture output
- Read - Read source code and documentation files
- Grep - Search for patterns in code
- Glob - Find files by pattern matching
- Write - Create test reports and documentation
- Task - Spawn specialized agents for unbiased evaluation of large/complex CLIs
These tools are part of Claude Code and require no additional setup.
If available on your system, the skill can use:
- asciinema - Record terminal sessions with full visual fidelity (captures colors, animations, spinners, formatting, and all visual output in real-time)
- agg - Convert asciinema recordings to animated GIF format for sharing
Install these tools for enhanced visual testing:
# macOS
brew install asciinema agg
# Ubuntu/Debian
apt-get install asciinema
# agg: cargo install agg
# Arch
pacman -S asciinema
# agg: cargo install aggYou: I'm building a new deployment CLI. Can you review the help system?
[Skill activates and tests help discovery, documentation, examples]
You: These error messages feel unclear. What would make them better?
[Skill analyzes error scenarios and suggests improvements with examples]
You: Review this library's API for developer experience
[Skill evaluates naming, consistency, documentation, and ergonomics]
The skill is installed in your personal Claude directory (~/.claude/skills/), so it automatically works with:
- ✅ CLI tools in any programming language
- ✅ Shell scripts and utilities
- ✅ Developer APIs and SDKs
- ✅ Terminal UI/TUI applications
- ✅ Any repository with command-line interfaces
You can customize the skill by editing files in ~/.claude/skills/cli-ux-tester/:
- SKILL.md - Adjust the UX framework or add new criteria
- testing-checklist.md - Add project-specific checklist items
- test-scenarios.md - Add custom scenarios for your domain
- scripts/example-test.sh - Adapt the test script template
rm -rf ~/.claude/skills/cli-ux-tester- Claude Code - The official CLI for Claude
- Bash 4.0+ (for test scripts)
Optional:
Contributions are welcome! Please read our Contributing Guidelines for details on:
- How to report issues and suggest enhancements
- Development setup and testing workflow
- Submitting pull requests
- Code style and documentation standards
Areas where contributions are especially valuable:
- Additional test scenarios for common CLI patterns
- More comprehensive checklist items
- Examples of good/bad CLI design from real tools
- Support for new CLI frameworks and patterns
- Documentation improvements and clarifications
MIT License - see LICENSE file for details.
This skill was created to make CLI development more user-centered by providing expert UX evaluation automatically within Claude Code sessions. It combines best practices from CLI design, developer experience research, and usability testing methodologies.
- CLI Guidelines - Comprehensive CLI best practices
- 12 Factor CLI Apps - Principles for building great CLIs
- GNU Command Line Interface Guidelines - Standards and conventions
- Better CLI - CLI Design Guide & Reference
- Claude Code Plugins: cli-ux-patterns - Another CLI UX skill focussed on visual evaluation.
- CLI UX Patterns & Best Practices - Another lighterweight CLI UX skill.
- Improving CLI progress displays - What progress displays to use when.
- UX patterns for CLI tools - Good UX patterns for CLI applications.
- 10 design prnciples for delightful CLIs - Priciples used to build Atlassian's Forge CLI.
- Heroku CLI Style Guide - Patterns used for Heroku CLI plugins.
- Small Sharp Software Tools by Brian P. Hogan - Building flexible command-line tools
- Powerful Command-Line Applications in Go by Ricardo Gerardi - Go CLI development
Built for use with Claude Code, leveraging the Claude Agent SDK's skill system for automatic context-aware activation.