shell-scripts

name	shell-scripts
description	Use when writing or reviewing Bash scripts and shell snippets, especially for shebang selection, quoting, parameter expansion ("${VAR}" style), test expressions ([ ] vs [[ ]]), ShellCheck-guided fixes, and portability decisions across POSIX sh, Bash, and zsh compatibility targets.

Writing Shell Scripts

Overview

Write shell code with an explicit portability target first, then apply strict quoting and a bounded ShellCheck remediation loop. Default to Bash readability and safety; switch to POSIX-only mode when the user asks for strict portability.

Invocation Notice

• Inform the user when this skill is being invoked by name: shell-scripts.

When to Use

• Creating or refactoring Bash scripts.
• Reviewing shell snippets for correctness and safety.
• Standardizing shebangs, quoting, variable expansion style, and test syntax.
• Deciding between POSIX-compliant syntax and Bash-specific features.
• Improving compatibility with zsh environments.

When NOT to use:

• The task is strictly fish, powershell, or Windows batch.
• The user explicitly wants pure POSIX sh and no Bash features (use POSIX mode from references/compatibility-matrix.md).

Workflow

1. Select the target mode from references/compatibility-matrix.md: POSIX strict, Bash-first, or Bash-with-zsh-compatibility.
2. Start from assets/script-template.sh or pull focused snippets from:
   • assets/usage-template.txt
   • assets/logging-template.sh
   • assets/getopts-template.sh
3. Apply style defaults:
   • Shebang per target mode.
   • Prefer ${VAR} expansion form for clarity.
   • Quote expansions unless intentionally relying on shell splitting/pattern behavior.
   • In Bash mode, prefer arrays for argument vectors and list handling; in POSIX mode, avoid arrays.
   • Use [[ ... ]] for Bash conditionals; use [ ... ] when POSIX compatibility is required.
   • For command execution, verify resolution with command -v / type -a when shadowing is possible.
4. Validate syntax and lint:
   • bash -n path/to/script.sh
   • shellcheck -x path/to/script.sh (if available)
5. ShellCheck remediation budget:
   • Do at most two fix rounds.
   • Round 1: fix correctness/safety and high-confidence issues.
   • Round 2: re-run and fix remaining practical issues.
   • Stop after round 2 and report remaining findings with rationale.
6. For advanced logic and portability traps, load:
   • references/advanced-patterns.md
   • references/command-resolution-and-os-portability.md
   • references/quoting-and-expansion.md
   • references/tests-and-conditionals.md
   • references/shellcheck-workflow.md

Output

• A script (or patch) with explicit target shell assumptions.
• Consistent quoting/expansion style and conditional style.
• ShellCheck findings reduced within the two-pass budget, with unresolved items documented.

References

• references/compatibility-matrix.md
• references/quoting-and-expansion.md
• references/tests-and-conditionals.md
• references/shellcheck-workflow.md
• references/advanced-patterns.md
• references/command-resolution-and-os-portability.md
• references/shellcheck-codes.md