Shell Scripts

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.

1. Start from assets/script-template.sh or pull focused snippets from:

• assets/usage-template.txt
• assets/logging-template.sh
• assets/getopts-template.sh

1. 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.

1. Validate syntax and lint:

• bash -n path/to/script.sh
• shellcheck -x path/to/script.sh (if available)

1. 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.

1. 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ahgraber
• Source: ahgraber/skills
• License: CC0-1.0

Install and usage instructions live in the source repository linked above.