AgentSkillsCN

bash-output-styler

利用gum结合ANSI回退功能，为Bash脚本赋予精美终端样式。 当您需要创建或修改面向用户的终端输出脚本时，请使用此工具。 当用户提出“美化Bash输出”“让脚本更美观”“为Shell脚本添加颜色”或“提升终端用户体验”等需求时，此工具同样适用。

SKILL.md
--- frontmatter
name: bash-output-styler
description: |
  Applies gorgeous terminal styling to bash scripts using gum with ANSI fallback.
  Use when creating or modifying bash/shell scripts that produce user-facing terminal output.
  Use when asked to "style bash output", "make pretty", "add colors to shell script", or "improve terminal UX".
license: MIT
user-invocable: true
argument-hint: "[script-path]"
metadata:
  author: tsilva
  version: "2.0.0"

Bash Output Styling

Style all user-facing shell script output using the bundled style.sh library.

Workflow

  1. •Read references/style.sh to understand available functions
  2. •If style.sh doesn't exist alongside the target script, copy from references/style.sh into the same directory
  3. •Source style.sh in the target script: source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/style.sh" 2>/dev/null || true
  4. •Replace raw echo statements with styled output function calls
  5. •Replace read -p prompts with confirm, input, or choose as appropriate
  6. •Wrap long-running commands with spin for animated feedback
  7. •Use table for structured multi-column data and progress for counted loops
  8. •Verify script still works when style.sh is missing (graceful degradation)

Color Palette

NameHexANSI 256Use
Brand#AF87FF141Headers, emphasis
Success#87D787114Checkmarks, completion
Error#FF5F5F203Errors, failures
Warning#FFD75F221Warnings, caution
Info#87CEEB117Info messages, tips
Muted#808080244Paths, secondary text

Output Functions

FunctionSymbolColorPurpose
header "brand" "subtitle"boxBrandBordered header
section "text"━━BrandHorizontal rule divider (fills terminal width)
success "text"✓SuccessCompleted actions
error "text"✗ErrorError messages
warn "text"⚠WarningWarnings
info "text"●InfoInformational
step "text"→MutedAction log (suppressed when quiet)
note "text"—Muted"Note:" prefixed
banner "text"boxSuccessCompletion banner
error_block "lines..."│ErrorMulti-line error box
list_item "label" "value"•Brand+MutedKey-value display
dim "text"—MutedDe-emphasized text (suppressed when quiet)
table "h1,h2" "v1,v2" ...boxBrand+MutedFormatted table with headers
progress cur total [label]████░░BrandInline progress bar

Interactive Functions

FunctionReturnsPurpose
confirm "prompt" [timeout] [affirm] [neg]Sets REPLYy/n prompt (backward-compatible)
spin "title" command [args...]Exit codeAnimated spinner wrapping a command
choose "header" "opt1" "opt2" ...stdoutInteractive selection menu
input "prompt" [placeholder] [--password]stdoutStyled text input

Pattern Mapping

Old PatternNew Pattern
echo "Title" + echo "====="header "Title" "Subtitle"
echo "✓ done"success "done"
echo "Error: ..."error "..."
echo "Warning: ..."warn "..."
echo " - Label: value"list_item "Label" "value"
read -p "Continue? (y/n) "confirm "Continue?"
echo "Section..." between blockssection "Section"
echo "Note: ..."note "..."
Multi-line error blockerror_block "line1" "line2"
select opt in ... / numbered menuchoose "Pick one:" "A" "B" "C"
read -p "Name: "input "Name:" "placeholder"
Long command with no feedbackspin "Installing..." brew install pkg
Aligned columns / status tablestable "Name,Status" "jq,installed"
Counter loop with echo progressprogress $i $total "Processing"

Environment Variables

VariableDefaultEffect
NO_COLORunsetDisables all color output when set to any value
STYLE_VERBOSE10=quiet (suppresses step/dim), 1=default, 2=verbose
COLORTERMunsetSet to truecolor or 24bit to enable RGB color palette

Rules

  • •ALWAYS source style.sh with fallback: source "$SCRIPT_DIR/style.sh" 2>/dev/null || true
  • •NEVER import gum directly in scripts — style.sh handles tool detection
  • •NEVER hard-code ANSI codes in scripts — use style.sh functions exclusively
  • •confirm function sets REPLY variable, compatible with existing [[ $REPLY =~ ^[Yy]$ ]] checks
  • •spin returns the wrapped command's exit code — use in conditionals: if spin "Building..." make; then ...
  • •choose and input return values via stdout — capture with: result=$(choose "Pick:" "A" "B")
  • •Do NOT wrap instant operations with spin — only use for commands that take noticeable time
  • •Interactive functions (choose, input, confirm) require a TTY — they read from /dev/tty
  • •Preserve all existing logic — only change output formatting, never behavior
  • •Scripts must work identically when style.sh is missing (plain echo fallback)