Linux Bash Scripting

Linux Bash Scripting — the meta-skill

Distro support

This meta-skill is how sk-* scripts stay two-family. A script must never hardcode apt, ufw, or apache2 — it calls the common.sh primitives, which resolve to the right tool for the detected family (Debian/Ubuntu or the RHEL family: Fedora, RHEL, CentOS Stream, Rocky, Alma, Oracle).

Full contract: references/common-sh-contract.md. Plan: docs/multi-distro/plan.md.

Use when

• Writing a new sk-* script in this repository.
• Reviewing or refactoring an existing script under scripts/.
• Checking whether a script matches the engine contract, flag model, and safety rules.

Do not use when

• The task is a one-off shell command or an operational fix that will not become a repo script.
• The implementation language is not Bash.

Required Inputs

Capability Contract

Review uses read/search access and is read-only by default. Editing an owned script requires explicit implementation authority; executing privileged or destructive paths requires separate test-host approval. Never use production state to discover what an unsafe script does.

Degraded Mode

Without shellcheck, a Bash runtime, root, or both distro families, complete static checks and label runtime, privilege, or family behaviour unassessed. Do not claim portability or safety from source inspection alone.

Decision Rules

Workflow

For every mutating sk-* script, apply the safe reversible operations standard: detect the family, capture a before state, support a dry-run or no-op path, make the operation idempotent, use atomic writes where files change, preserve ownership/labels, and expose a bounded rollback or recovery path. A script is not release-ready until its success path, already-correct path, invalid-input path, and rollback/recovery evidence are tested for both distro families or explicitly marked unassessed.

1. Read the owning skill, engine spec, inventory, template, and common.sh contract.
2. Define inputs, effects, decisions, exit codes, rollback, and family support; stop on an unresolved destructive default.
3. Scaffold or review the six-section structure and standard flags.
4. Implement through shared primitives with quoted inputs, safe temp files, backups, and native validators.
5. Test help, bad inputs, --yes, dry run, interruption, idempotency, and both families where claimed.
6. Recover failed mutation from backup, then run shellcheck/engine lint and reconcile manifest documentation.

Evidence Produced

Quality standards

• Every script must be safe, idempotent by default, and compatible with human and agent callers.
• common.sh is mandatory; do not reinvent shared behavior.
• Help output, failure modes, and validation-before-reload rules must be explicit.

Anti-patterns

• Bypassing common.sh. Fix: use its output, guard, package, service, and file primitives.
• Treating --yes as permission to invent defaults. Fix: require every decision flag.
• Shipping without a manifest entry. Fix: reconcile the owning skill and inventory.
• Using set -e. Fix: handle expected failures and preserve set -uo pipefail.
• Writing important files with direct redirection. Fix: back up and use atomic writes.
• Claiming family portability after one-family testing. Fix: test both or mark one unassessed.

Outputs

Worked Example

For sk-cifs-mount, make share, mount point, and credentials source explicit flags. Under --yes, missing any required choice exits 2; dry run prints package, credential-file, mount, and fstab actions without exposing the password or writing files.

References

• ../../docs/continuous-improvement/safe-reversible-operations-standard.md

• ../../docs/continuous-improvement/two-family-validation-and-recovery.md

• references/script-template.sh

• references/common-sh-contract.md

• references/interactive-ux.md

• docs/engine-design/spec.md

This skill is the foundation every other script in linux-skills is built on. Before writing a new sk-* script, or reviewing an existing one, load this skill.

It defines:

1. The canonical script template (six-section layout from Pro Bash).
2. The common.sh library contract (what functions exist, what they do).
3. The standard flag set every script must support.
4. Interactive UX rules (prompts, confirmations, output).
5. Safety patterns every script must follow.
6. How Claude Code invokes these scripts non-interactively.

Read the full engine spec in docs/engine-design/spec.md and the script catalogue in docs/engine-design/script-inventory.md for context.

When to use this skill

• Before writing any new script in scripts/.
• Before reviewing a script that another person (or another Claude session) wrote.
• When asked "how do I make a script interactive / secure / safe / dry-runnable / help-printing?"
• When unsure which library function to call from common.sh.

When NOT to use this skill

• For one-liners and ad-hoc commands (don't over-engineer a grep).
• For Python, Node.js, Go, or any non-Bash tooling.
• For scripts that will never live in this repo (e.g. throwaway fixes).

The canonical script template

Every sk-* script must start from this six-section layout. See references/script-template.sh for a copy-pasteable version. To create a new script, the recommended flow is:

sudo sk-new-script <skill-name> <script-name>   # scaffolds from template

The six sections in order:

1. Metadata header — #: prefixed comments with Title, Synopsis, Description, Author, Contact, Version. Grep-extractable. Author line must always read #: Author: Peter Bamuhigire <techguypeter.com>.
2. Library + safety — set -uo pipefail then source of common.sh. Never use set -e (it interacts badly with traps and function return codes).
3. Defaults — every tunable as a top-level variable with its default. No magic numbers deep in the script.
4. Functions — helpers, including a usage() that prints every flag the script accepts.
5. Flag parsing — call parse_standard_flags "$@", then parse script-specific decision flags from REMAINING_ARGS.
6. Sanity checks — require_root, require_family <debian|rhel|any>, require_cmd, and any require_flag calls for --yes mode.
7. Main logic — the work, expressed via header, pass, warn, fail, info, and run.

The common.sh library contract

common.sh is the shared library every script sources from /usr/local/lib/linux-skills/common.sh. The full function contract lives in references/common-sh-contract.md — read it before calling a new function. Summary:

Output

Always use these. Never roll your own echo -e "\033[31m...".

Guards

Interaction (skipped under --yes)

Safe file operations

Flag parsing

Standard flags — mandatory on every script

Every script must support these flags via parse_standard_flags:

The --yes contract (non-negotiable)

--yes means "the caller has pre-committed to every decision". It does not mean "accept safe defaults." If a script would normally prompt for a required input and the caller did not supply a flag for it, the script must abort:

ERROR: --yes was passed but --domain is required.
       Run `<script> --help` to see required flags.

This rule exists because Claude Code invokes scripts non-interactively and must get exactly the outcome it asked for — silent defaults are a footgun.

Interactive UX rules

When running interactively (no --yes), scripts must feel friendly at a terminal. See references/interactive-ux.md for the full rule set. Key points:

• Announce before acting. Every destructive step prints what it is about to do, then asks to confirm.
• Show progress. Long-running steps use header to mark phases.
• PASS / WARN / FAIL is the output grammar. Use pass, warn, fail, info — never ad-hoc echo.
• Explain failures. When a check fails, say why in plain English and point at the remediation (another sk-* script, a config file, a man page).
• Colors are semantic. Green = good; yellow = watch; red = broken; cyan = neutral information. Never decorate.
• Confirm destructive operations with a typed word, not a single letter. Use confirm_destructive, which requires the user to type yes.
• Ctrl-C is a first-class exit path. The trap installed by common.sh ensures a clean exit. Don't fight it.
• Help text must be complete. Every decision flag listed. Examples included. Fits on one screen where possible.

Safety patterns every script must follow

These rules are enforced by sk-lint (the pre-commit linter) and checked in code review. Violations block a merge.

1. Source common.sh — never reimplement colors, prompts, traps.
2. set -uo pipefail — always. Never set -e.
3. Quote every variable — "$var", "${array[@]}", always.
4. IFS= read -r — every read, every time.
5. Parameter expansion over sed/awk — ${var##*/} for basename, ${var%.*} for removing a suffix. Faster and safer than subprocessing.
6. Atomic file edits — write to $target.new, then mv. Never > file on anything important. Use atomic_write or backup_file first.
7. Safe temp files — safe_tempfile, which auto-registers a cleanup trap.
8. Validate with case, not sprawling regex — from Pro Bash. Easier to read, easier to extend, easier to debug.
9. printf over echo — printf '%s\n' "$var". echo's behavior varies.
10. "$@" (quoted) when forwarding args. Unquoted $@ word-splits.
11. Exit codes matter — 0 success, 1 generic failure, 2 usage/flag error, 3 precondition failed, 4 user aborted, 5 dependency missing.
12. Never eval untrusted input. No exceptions.
13. Validate external configs before reload — nginx -t, apache2ctl configtest, visudo -c, sshd -t, named-checkconf. Every time.
14. Destructive operations write a timestamped audit line to /var/log/linux-skills/<script>.log regardless of --log.
15. Every script passes shellcheck with zero warnings. Run sk-lint before committing.

Scripts

This skill installs the following scripts to /usr/local/bin/. To install:

sudo install-skills-bin linux-bash-scripting

How Claude Code invokes these scripts

When Claude Code is asked to do something that maps to a script in this toolkit, it must:

1. Discover — check command -v sk-foo to see if the script is installed. If not, suggest sudo install-skills-bin <skill-name>.
2. Read help — run sk-foo --help to see the required decision flags.
3. Pre-commit — decide every required input up front (domain, user, port, path, etc.). Never call with --yes and hope a default saves the day.
4. Dry-run first — when uncertain, run with --dry-run --yes --<flags> to preview.
5. Invoke — run with --yes --log --<flags>.
6. Interpret — parse PASS/WARN/FAIL counts from output; if --json is supported, use it.

If any step of this loop isn't possible (e.g. the script doesn't have the flag we need), that's a script bug — file it against the inventory, not a silent workaround.

References

• references/script-template.sh — the canonical six-section template.
• references/common-sh-contract.md — full function contract for the shared library.
• references/interactive-ux.md — interactive UX rules in detail.
• docs/engine-design/spec.md — the binding engine specification.
• docs/engine-design/script-inventory.md — the curated catalogue.