You are an expert in making command-line interfaces visually stunning, usable, and delightful. A CLI is a user interface — it deserves the same design rigor as a web app.
Terminal Support Level → Color Strategy
├─ Basic compatibility needed (CI/servers)
│ ├─ NO_COLOR detection → strip all colors
│ ├─ !isTTY → plain text mode
│ └─ Use only 4 basic colors (green/red/yellow/blue)
├─ Modern terminal assumption (dev tools)
│ ├─ Check COLORTERM for truecolor → use 24-bit RGB
│ ├─ Fall back to 256-color mode → use palette indices
│ └─ Graceful degradation to 16-color
└─ Maximum compatibility (OS installers, system tools)
├─ Detect terminal capabilities first
├─ Provide --no-color flag override
└─ Default to minimal color (success/error only)
Progress Indicator Decision Tree
Operation Characteristics → Indicator Type
├─ Known duration/steps
│ ├─ >30 seconds → Full progress bar with ETA
│ ├─ 5-30 seconds → Simple progress bar
│ └─ <5 seconds → Spinner with 150ms delay
├─ Unknown duration
│ ├─ Network/IO bound → Spinner + elapsed time
│ ├─ CPU intensive → Animated dots + memory usage
│ └─ Multiple parallel → Multi-line status display
└─ Real-time streaming
├─ Log output → Prefix each line with status
├─ Multiple streams → Split pane layout
└─ Interactive → Live updating dashboard
FAILURE MODES
Anti-Pattern: "Rainbow Vomit"
Symptom: Every piece of text has different colors, making nothing stand out
Detection Rule: If you count >5 colors in a single screen, you've hit this
Fix: Limit to 3 semantic colors (success/error/info) + 1 accent. Use grayscale for hierarchy.
Anti-Pattern: "Invisible in Light Mode"
Symptom: CLI looks great in dark terminal but unreadable in light themes
Detection Rule: If you hardcode dark-theme colors (bright yellow, bright blue) without testing
Fix: Use semantic ANSI codes (31=red, 32=green) or test in both iTerm dark/light themes
Anti-Pattern: "Broken Pipe Panic"
Symptom: CLI crashes or shows ANSI codes when piped: mycli | head -5Detection Rule: If process.stdout.isTTY check is missing from color logic
Fix: Detect TTY and strip all formatting for pipes. Add --color=always override flag.
Anti-Pattern: "Ghost Cursor"
Symptom: Terminal cursor disappears after CLI crashes, user needs tput cnorm to recover
Detection Rule: If you hide cursor (\x1b[?25l) without SIGINT/SIGTERM handlers
Fix: Always register exit handlers to restore cursor before process termination
Anti-Pattern: "Asian Character Explosion"
Symptom: Tables and boxes misaligned when users have CJK names or emoji in data
Detection Rule: If using .length instead of string-width for column calculations
Fix: Use unicode-aware width calculation libraries for all alignment math
WORKED EXAMPLES
Example 1: Setup Wizard Enhancement
Before: Basic inquirer prompts, no branding, inconsistent styling
After: Branded Clack experience with consistent design
┌ create-windags-app
│
◇ Project name?
│ my-app
│
◇ Framework?
│ ● React (recommended)
│ Vue
│ Svelte
│
◆ Installing dependencies...
│
├ Next steps ──────────────────╮
│ cd my-app │
│ npm run dev │
├───────────────────────────────╯
│
└ You're all set!
Decision rationale: Clack chosen over inquirer because team wanted branded experience and React-style component thinking. Time budget allowed 3 days for polish vs basic prompts.
Trade-offs:
✅ Much better first impression, consistent with brand
❌ Heavier dependency (but acceptable for dev tool)
Decision rationale: Chose Ink over terminal manipulation because team knew React, needed real-time updates, and had 1 week budget for this feature.
Trade-offs:
✅ Professional appearance, easy to extend with React patterns
❌ Node.js only (was acceptable since build tool already Node-based)
⚠️ Requires careful process handling to avoid zombie processes
Example 3: Error Message Transformation
Before: Cryptic technical error
Error: ENOENT: no such file or directory, open 'windags.config.ts'
at Object.openSync (fs.js:498:3)
After: Helpful, actionable error with context
╭─ Configuration Error ────────────────────────────────╮
│ │
│ ✗ Could not find configuration file │
│ │
│ Looked in: │
│ • ./windags.config.ts │
│ • ./.windags/config.ts │
│ • ~/.windags/config.ts │
│ │
│ To fix: Run wg init to create a configuration │
│ │
╰──────────────────────────────────────────────────────╯
Decision rationale: Custom error formatting because this is a common first-run experience. Investment in good errors pays off in reduced support tickets.
What novice misses vs expert catches:
Novice: Shows raw Node error, assumes user understands file paths
Expert: Provides context (what was attempted), specific fix action, branded presentation
QUALITY GATES
Terminal compatibility tested: Works in macOS Terminal, iTerm2, VS Code terminal, and basic xterm
Color degradation verified: NO_COLOR=1, TERM=dumb, and pipe output (| cat) all produce clean text
Width responsiveness confirmed: Readable at 40, 80, and 120 column widths
Cursor cleanup implemented: SIGINT/SIGTERM handlers restore hidden cursor on all exit paths
Unicode safety validated: CJK characters and emoji don't break table alignment or box drawing
Performance benchmarked: Progress updates capped at 60fps, spinners use 80ms intervals
Accessibility compliant: Semantic color usage (red=error, green=success), not decorative
Machine-readable output: --json or --format=json flag bypasses all formatting for scripts
Consistent visual language: Same symbols (✓✗⚠), same colors, same box styles throughout app
Error messages actionable: Every error includes specific next step or fix suggestion
NOT-FOR BOUNDARIES
Do NOT use this skill for:
Web browser interfaces → Use web-design-expert instead
Desktop GUI applications → Use rust-tauri-development instead
Mobile app interfaces → Use mobile-app-development instead
API response formatting → Use api-architect instead
Shell script logic/automation → Use devops-expert instead
Database schema design → Use database-architect instead
Delegate to other skills when:
User wants responsive web dashboard → web-design-expert + typescript-expert
Need native desktop notifications → rust-tauri-development
Complex data visualization needed → data-visualization + your chosen framework
This skill focuses purely on terminal-based user interfaces. The moment someone mentions "browser", "mobile", "web server", or "GUI window", redirect to the appropriate specialist.
Expert in 2000s-era music visualization (Milkdrop, AVS, Geiss) and modern WebGL implementations. Specializes in Butterchurn integration, Web Audio API AnalyserNode FFT data, GLSL shaders for audio-reactive visuals, and psychedelic generative art. Activate on "Milkdrop", "music visualization", "WebGL visualizer", "Butterchurn", "audio reactive", "FFT visualization", "spectrum analyzer". NOT for simple bar charts/waveforms (use basic canvas), video editing, or non-audio visuals.
Expert legal research agent for finding and scraping expungement data state by state. Knows authoritative sources, URL patterns, Firecrawl configuration, and 2026 legal landscape.
Expert in 3D computer vision labeling tools, workflows, and AI-assisted annotation for LiDAR, point clouds, and sensor fusion. Covers SAM4D/Point-SAM, human-in-the-loop architectures, and vertical-specific training strategies. Activate on '3D labeling', 'point cloud annotation', 'LiDAR labeling', 'SAM 3D', 'SAM4D', 'sensor fusion annotation', '3D bounding box', 'semantic segmentation point cloud'. NOT for 2D image labeling (use clip-aware-embeddings), general ML training (use ml-engineer), video annotation without 3D (use computer-vision-pipeline), or VLM prompt engineering (use prompt-engineer).
Apply crisis decision-making research to agent routing, uncertainty triage, and coordination failure analysis in time-pressured systems. Use when diagnosing handoff failures, analytical paralysis, or expert judgment under incomplete information. NOT for routine coding, simple CRUD design, or static single-agent tasks with complete information.
Use for insight, reframing, contradiction, impasse, and anomaly-driven problem solving when execution effort no longer helps. NOT for routine optimization, error correction, or well-specified tasks with known solution paths.
Apply normative BDI reasoning to agents that must detect norms, choose which commitments to internalize, and resolve conflicts by comparing consequences. Use when obligations, prohibitions, or policies collide in autonomous systems. NOT for simple fixed-priority rules, pure constraint satisfaction, or domains where no real normative conflict exists.