bash-best-practiceslisted
A standard for sh and bash utilities and CLI wrappers: one script shape, help as the single source of truth, portability to the bash 3.2 and BSD userland macOS ships, measured pitfalls, the zsh harness, completions kept honest by machine, shellcheck and shfmt doctrine, and check-sh.sh, a travelling checker holding help, docs and completions to the dispatcher. Use when writing, reviewing or refactoring a shell script or CLI wrapper, adding a subcommand, a flag, an exit code or a completion, choosing which bash a script needs, making a script run on macOS, reading a shellcheck or shfmt finding, or when an ad-hoc command misbehaves in the agent's shell. Triggers: bash, sh, shell script, shebang, set -euo pipefail, --help, usage, subcommand, exit code, completion, compdef, shellcheck, shfmt, bash 3.2, macOS bash, mapfile, readlink -f, pipefail, zsh, напиши bash-скрипт, shell-скрипт, почини скрипт, проверь скрипт, добавь флаг, добавь подкоманду, автодополнение, коды возврата, не работает на маке, вывод --help.
rokokol/bash-best-practices-skill · ★ 0 · Code & Development · score 75
Install: claude install-skill rokokol/bash-best-practices-skill
# bash-best-practices
A shell script is read by three things: a person, its own `--help`, and a completion. The code is the only one of them that is executed, so the code is the only truth, and everything else — the help, a table in a readme, the words a completion offers — is held to it by a machine rather than by memory. Two accounts of one thing disagree within a month; a list nobody checks is a list that has already drifted
The second truth is the machine the script runs on. These utilities travel to macOS, where `/bin/bash` is 3.2 and the userland is BSD, so "works here" is never the claim. The claim is the line in the header that says which bash the script needs, and that line is checkable
The core below is what every script of the family shares. [`check-sh.sh`](check-sh.sh) beside this file is the mechanical half: it reads a script's dispatcher, parsers and exit codes out of the source and holds the help, the documents and the completions to them, in both directions, proving each of its own checks able to fail on every run
## Doing the work
- **Start a new script from `./check-sh.sh --template > NAME.sh`**, which is the shape below already assembled; `--template bash` and `--template zsh` print its two completions
- **End every change with `./check-sh.sh NAME.sh`**, plus `-d DOC` for each document that lists its subcommands, `-m DOC` for each that only mentions some, and `-c BASH ZSH` where completions exist; a repository's gate runs the same line, and `./check-sh