developing-simple-bash-scripts skill

This skill defines guidelines for writing simple Bash scripts: ad-hoc tasks, short wrappers, linear logic, or internal-use scripts that do not need full CLI scaffolding.

Prioritise correctness and brevity. Do NOT pad simple scripts with template boilerplate.

If a script grows beyond ~50 lines, needs 3+ flags, or involves complex control flow, switch to the developing-complex-bash-scripts skill instead.

When to Use This Skill

• Ad-hoc or one-off automation tasks

• Simple wrappers around existing commands

• Linear logic with no or minimal branching

• Scripts expected to stay under ~50 lines

• No need for --help , structured logging, or multiple named flags

Core Requirements

Shebang & Safety Modes

Every script, no matter how simple, MUST start with:

#!/usr/bin/env bash

set -o errexit -o nounset

• errexit : exit immediately on error.

• nounset : exit on reference to an unset variable.

• errtrace is optional for simple scripts.

• Do NOT add set -o pipefail globally unless the script has critical pipe chains that must be checked.

Tooling

• All scripts MUST pass shellcheck without warnings.

• Format with shfmt before considering the script done.

Logic & Control Flow

Conditionals: always use [[ ... ]] , never [ ... ] .

Use case for pattern matching or multiple-branch decisions.

Prefer guard clauses to keep nesting shallow:

Bad

if [[ -f "${file}" ]]; then process "${file}" else echo "File not found" >&2 exit 1 fi

Good

if [[ ! -f "${file}" ]]; then echo "File not found: ${file}" >&2 exit 1 fi process "${file}"

Variables & Quoting

• Always use ${var} (braces) for variable expansion.

• Always quote expansions: "${var}" — prevents word-splitting and glob expansion.

• Use descriptive variable names; avoid magic numbers.

Output

• Use echo or printf for normal output.

• Write errors to stderr: echo "error message" >&2 .

• Positional arguments ("${1}" , "${2}" ) are fine for simple inputs.

Minimal Example

#!/usr/bin/env bash

set -o errexit -o nounset

src="${1:?Usage: $0 <src> <dst>}" dst="${2:?Usage: $0 <src> <dst>}"

if [[ ! -f "${src}" ]]; then echo "Source file not found: ${src}" >&2 exit 1 fi

cp "${src}" "${dst}" echo "Copied ${src} -> ${dst}"

Upgrade Checklist

Refactor a simple script into a complex script when any of the following apply:

• Script exceeds ~50 lines of logic

• Needs 3 or more named flags / options

• Requires structured logging (log_info , log_error , etc.)

• Needs --help output

• Has non-trivial error handling or cleanup logic

• Will be shared or reused as a production tool