shell-scripting

Sub-Skill: Bash / POSIX Scripting

Purpose: Prevent silent failures, portability bugs, and security holes in shell scripts by enforcing safe defaults, clean structure, and ShellCheck compliance.

---

Rules

Safety & Error Handling

1. Fail-fast header. Always begin every shell script with set -euo pipefail so that unset variables, failed commands, and pipeline errors abort execution immediately. Reference: ERR-2026-021

2. Trap cleanup. Always register a trap 'cleanup' EXIT function to remove temp files and release locks even when the script exits early due to an error.

3. Meaningful exit codes. Always exit with a non-zero code that reflects the failure category (e.g., exit 1 for usage errors, exit 2 for dependency missing); never exit with 0 on failure.

4. No eval. Never use eval to construct or execute dynamic commands; prefer arrays or explicit argument lists to avoid injection vulnerabilities.

Variables & Quoting

1. Quote every variable. Always double-quote variable expansions ("$var", "$@") to prevent word-splitting and glob expansion on values containing spaces or special characters.

2. Declare locals. Always declare variables inside functions with local to prevent accidental global namespace pollution.

3. Readonly constants. Use readonly for values that must not change after assignment (e.g., readonly SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)").

Portability & Compatibility

1. POSIX shebang. Always start scripts with #!/usr/bin/env bash (or #!/bin/sh for strict POSIX); never rely on /bin/bash being present at a fixed path on all target systems.

2. Portable syntax. Prefer POSIX-compatible constructs ([ ] over [[ ]], $(...) over backticks) when the script must run under /bin/sh; use Bash-specific features only when the shebang explicitly targets Bash.

3. ShellCheck clean. Ensure every script passes shellcheck -S warning with zero warnings before committing; treat ShellCheck output as mandatory, not advisory.