fancy-interactive-bash
Use when creating or refactoring interactive Bash scripts that should be composable, sourceable, color-aware, testable by function, and structured around parse_opts, parse_prereqs, and a sequential run_main orchestration.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- fancy-interactive-bash
- group
- shell-bash
- summary
- Quality Bash pattern: parse_opts/parse_prereqs/run_main, sourceable functions, color UX, testable by function.
- description
- Use when creating or refactoring interactive Bash scripts that should be composable, sourceable, color-aware, testable by function, and structured around parse_opts, parse_prereqs, and a sequential run_main orchestration.
02 资源文件 4
- 资产文件assets/bin-lint-template634 B
- 资产文件assets/bin-test-template570 B
- 脚本assets/script-template.sh2.8 KB
- 脚本assets/script-template.test.sh1.8 KB
03 SKILL.md 正文
Fancy Interactive Bash
Use this skill for Bash utilities where the implementation quality matters more than the domain logic.
The goal is not "write a script that works once". The goal is:
- sourceable for tests
- deterministic in small functions
- pleasant in terminal use
- easy to extend without turning
maininto a blob
Template Files
Starter templates are in assets/: script-template.sh, script-template.test.sh, bin-test-template, bin-lint-template.
Copy them as starting points and adapt names immediately to avoid leaking placeholders.
Default Shape
Prefer this structure:
#!/usr/bin/env bash
# shellcheck shell=bash
set -euo pipefail
# Global flags and cached state
# Colors
usage() { ... }
log() { ... }
color_print() { ... }
info() { ... }
success() { ... }
warn() { ... }
error() { ... }
verbose() { ... }
parse_opts() { ... }
parse_prereqs() { ... }
# Pure helpers and formatting helpers
# Inventory / planning helpers
# Apply / mutate helpers
run_main() {
parse_opts "$@" || return $?
parse_prereqs
plan_phase_one
apply_phase_one
plan_phase_two
apply_phase_two
report_summary
}
if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
run_main "$@"
fi
Core Rules
- Keep
run_mainas a readable sequence of function calls. - Do not hide orchestration inside one giant helper.
- Separate planning/reporting from mutation when practical.
- Make most helpers callable independently after
source script. - Prefer small functions with single responsibility over local cleverness.
- Keep state in explicit globals with a clear prefix, not anonymous shell variables.
- Run
shellcheckduring development and before considering the script finished. - If
shellcheckwarnings are intentionally suppressed, keep the suppression narrow and explain why.
Validation Workflow
Treat testing and linting as script contract, not follow-up chores.
Script level:
- Add
*.test.shsibling for each script (bin/foo→bin/foo.test.sh) - Keep tests small, readable, assertion output clear (expected vs actual)
- Print colored
[PASS]/[FAIL]markers at line start - Cover option parsing, defaults,
--help, symmetry, formatters, interactive fallbacks, progress/failure shapes
Repository level:
bin/test: discover and run all*.test.shfiles in stable order; per-file heading before each; fail fast; apply color to headings (cyan/aqua works well)bin/lint: standard shellcheck entrypoint; per-file headings with same color scheme; fail non-zero on lint errors- Both should have reproducible per-file lines so failures can be retried directly
Developers run bin/lint && bin/test before commit.
Naming
Normalize the reusable top-level contract to:
parse_opts: parse flags and mode selectionparse_prereqs: detect tools, terminal capabilities, required binaries, and environment constraintsrun_main: linear orchestration only
Other helpers should be named by role:
*_usage*_info,*_warn,*_error,*_success*_format_**_plan_**_apply_**_interactive_select_**_progress_*
Option Design
Support common flags users will try even before they read help:
-h,--help-n,--dry-run--verbose--trace--timings-i,--interactive--color--no-color--raw,--shortwhen you have machine-lean or condensed output modes--plain,--progressivewhen output mode can change materially--allwhen multiple groups/checks/actions can be enabled at once--fooand--no-foopairs for toggles
Rules:
- Positive group flags should allow "only mode" semantics when relevant.
--no-xmust work symmetrically with--x.- Unknown options should print a warning, show usage, and exit non-zero.
--helpshould print usage and exit without running work.--verboseshould expose useful per-step detail without becoming shell trace noise.- Support
--timingswhen runtime cost matters and users need to see where time is going. - Keep
--traceseparate from--verboseso debugging command execution stays opt-in.
Output and Color
Treat terminal output as part of the interface. Principles apply to Bash, Go, Python, and any CLI tool.
TTY detection: Auto-disable color when output is piped/redirected. Detect via [[ -t 1 ]] (Bash), os.Stat (Go), sys.stdout.isatty() (Python). Optionally support --color/--no-color flags. All output must remain readable without color.
Vibe palette (mandatory): Every colored CLI created or refactored with this skill uses this semantic palette. Do not substitute an ad-hoc palette. Emit these sequences only when color is enabled; preserve readable plain output for NO_COLOR, --no-color, and non-TTY output.
| Element | ANSI color | Used For |
|---|---|---|
| Dim | gray | descriptions, prose, non-critical text, debug output |
| Bold | bright | structural markers, emphasis |
| Heading | yellow (33), bold |
section labels (Usage:, Flags:, Examples:) |
| Command | green | executable tokens, subcommands |
| Flag | green | option names |
| Placeholder | bright magenta (95) |
metavariables (<issue-key>, [FILE]) |
| File heading | cyan/aqua | per-file labels in test/lint output |
| Tool name | magenta (35), bold |
primary brand, usage first line |
| Success | green | completion, [PASS] |
| Error | red | failure, [FAIL], error lines |
Apply to:
- Help section headings and tool name
- Subcommand tokens separately from placeholders (separate colors so command shape scans fast)
- Option names in help
info(),success(),warn(),error()output- Test/lint runner headings
[PASS]/[FAIL]markers- Dim text: Debug output, verbose trace lines, auxiliary information user can ignore (e.g., when
--verboseshows step-by-step progress, use dim for "entering step X" context)
Rules:
- One central abstraction.
color_printhelper in Bash,colorpackage in Go — not scattered codes. - Token-level, not full-line. Color individual tokens (command, flag, placeholder) not entire usage line.
- Consistent across the tool. Same palette for help, test output, error messages, runner headings.
- Consistent across languages. Bash script and Go CLI in same project should feel identical to users.
- Use the Vibe palette exactly. Do not change token colors for individual tools; the semantic split is part of the shared CLI interface.
The supplied assets/script-template.sh encodes this palette for new Bash tools.
Performance And Timings
Make slow steps visible without noise.
Split flags:
--verbose: what's happening--timings: where time is going--trace: exact commands
Rules:
- Default output concise
- Time meaningful phases (not every helper):
parse_prereqs, discovery, planning, selectors, external commands, final report - In
--verbose: show timing next to step when it clarifies slowness - In default mode: keep timings in
--timingsor summary only - Include elapsed time on failure when diagnostic
- One timing helper, not scattered
datecalls; prefer monotonic timers, fall back cleanly - Store per-step data for summary; don't couple timing to color/TTY logic
Pattern: run_timed "Step name" step_function → Completed in 12.4s
Interactivity
Interactive mode should be optional, not structural.
Rules:
- The script must still work non-interactively.
- If
fzfor a similar tool is available, use it for multi-select review. - If it is not available, fall back to one-at-a-time confirmation or plain prompts.
- Print a protip when an optional tool would improve UX.
For fzf-style selectors:
- visible columns should show meaningful labels, not raw payload fields
- raw paths/ids may remain hidden as the returned value
- support bulk select/deselect bindings
- include short usage hints in the prompt/header
- keep row formatting deterministic so tests can assert it
Progress UI
For longer work, render progress on the same line when stdout is a TTY.
Rules:
- gate live rendering behind
[[ -t 1 ]] - provide explicit start/status/finish helpers
- clear previously rendered status lines before printing final output
- truncate long paths to terminal width
- prefer stable two-line status when current target/path matters
Do not make progress rendering a dependency of correctness. It is presentation only.
Failure Handling
Always tell the user what to do next when a chained command fails.
Rules:
- print the failing step clearly
- print exit status when available
- if a line number or source line can be inferred, show it
- end with a concrete next step
Typical next-step guidance:
- rerun with
--verbose - rerun with
--timings - rerun with
--trace - rerun a single group with
--foo - install optional dependency such as
fzf - fix prerequisite access such as
sudoor missing binary - run the suggested safer command instead of deleting raw files
Failure output should explain the recovery path, not just the error.
Composability
Write the script so functions can be tested in isolation.
Preferred patterns:
- direct sourcing via
source script, guarded with[[ "${BASH_SOURCE[0]}" == "$0" ]] - explicit reset helper in tests for all globals
- helper functions return data via stdout when practical
- orchestration functions call helpers that can be overridden in tests
- avoid hidden subshell-only state unless required
This matters more than "pure shell minimalism". A sourceable script with overridable helpers is easier to verify.
Testing Method
Test structure and behavior via source and function override.
Coverage: Option parsing, defaults/reset, --help, flag symmetry, formatters, interactive fallbacks, progress/failure shapes, orchestration, environment branches.
Method:
- Source the script; override helpers to isolate units
- Use temp directories, not fixtures
- Assert exact strings (formatted rows, prompts); separate exit code assertions
- Run
shellcheckas required validation - Print colored
[PASS]/[FAIL]at line start - Show expected vs actual clearly on failure
- Use parameterized loops when they add signal, not noise
Helpers: assert_eq, assert_status, reset_state
Test runner UX: Section headers, colored [PASS] / [FAIL], fail fast on structural regressions.
What To Reuse From The Source Pattern
Extract and reuse these methods:
- centralized color handling, including help/usage output
- a consistent family of
info/success/warn/error/verbosehelpers - symmetrical option parsing with intuitive defaults
- explicit parsing and prerequisite phases
- sequential
run_main - plan/apply separation
- interactive selectors as separate functions
- progress helpers separate from business logic
- failure handlers that include next steps
- a direct-source entry guard for tests using
BASH_SOURCE - tests that override helpers to isolate units
What To Ignore
Ignore the actual business purpose of the script.
Do not copy:
- cleanup-specific paths
- runtime-specific commands
- app-specific heuristics
- domain-specific group names
Copy the engineering pattern, not the business logic.
Skeleton
parse_opts() {
while (($#)); do
case "$1" in
-h|--help) usage; return 1 ;;
-n|--dry-run) FLAG_DRY_RUN=1 ;;
--verbose) FLAG_VERBOSE=1 ;;
-i|--interactive) FLAG_INTERACTIVE=1 ;;
--color) FLAG_COLOR=1 ;;
--no-color) FLAG_COLOR=0 ;;
--all) FLAG_ALL=1 ;;
--thing) enable_only_mode; FLAG_THING=1 ;;
--no-thing) FLAG_THING=0 ;;
*) warn "Unknown option: $1"; usage >&2; return 2 ;;
esac
shift
done
}
parse_prereqs() {
command -v fzf >/dev/null 2>&1 && HAS_FZF=1 || HAS_FZF=0
}
run_main() {
parse_opts "$@" || return $?
parse_prereqs
plan_work
apply_work
report_summary
}
Use this as the starting contract unless the script is trivial enough that the extra structure would be fake ceremony.
04 同仓库更多 Skills
maintainer-workflow-commands
Use when adding or auditing project commands for setup, development, tests, lint, dependencies, troubleshooting, or releases, and when making those commands discoverable through bin/workflows.
writing-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment
writing-plans
Use when you have a spec or requirements for a multi-step task, before touching code
wrap-up
Scan the current conversation and produce a structured session close-out: deferred items, open questions, decisions made, and the single clearest next action. Ends with a ready-to-paste "next session opener" prompt. Use this skill whenever the user says "/wrap-up", "/deferred", "wrap up this session", "what did we defer", "what's left", "end of session summary", or asks what to pick up next time.
verification-before-completion
Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
using-superpowers
Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions