developing-shell-scripts

name: developing-shell-scripts description: Use when writing or reviewing `.sh`, `.bash`, or `.zsh` files, Makefile shell snippets, CI shell commands, or choosing between Zsh, Bash, and POSIX `sh` in this repo.

Developing Shell Scripts

Overview

Choose the simplest shell that meets the runtime constraints, then make the script explicit about safety, dependencies, and I/O behavior. In this repo, prefer Zsh for developer-facing scripts when availability allows, then Bash, then POSIX sh.

When to Use

Writing or reviewing shell scripts in this repo
Adding shell snippets to Makefiles or CI configuration
Choosing between Zsh, Bash, and POSIX sh
Hardening script error handling, quoting, option parsing, or cleanup behavior

Do not use this skill for non-shell implementation work or as a substitute for checking the runtime environment the script will actually run in.

Quick Reference

Context	Default
Developer-facing script on macOS/Linux	Zsh with `#!/usr/bin/env zsh`
CI or minimal container	Bash with `#!/usr/bin/env bash`
Maximum portability	POSIX `sh` with `#!/bin/sh`
Safety prologue	`set -euo pipefail` for Bash, add `-E` when relying on ERR traps, use `set -eu` for `sh`, and `emulate -L zsh` plus explicit options in Zsh functions
Output channels	stdout for actual output, stderr for errors and diagnostics
Tool preference	Shell built-ins first, then standard utilities, then `npx`, then `python`
Bash script directory	Resolve the script file with `realpath -- "${BASH_SOURCE[0]}"`, then derive its directory with parameter expansion
Static checks	ShellCheck and `shfmt` for `sh` or Bash, and `zsh -n` for Zsh

Implementation

Use shell-specific extensions and shebangs for executable scripts; omit the shebang only for sourced shell libraries
Keep scripts self-contained and do not rely on interactive init files such as .zshrc or .bashrc
In Bash scripts, locate the script with script_path="$(realpath -- "${BASH_SOURCE[0]}")" and script_dir="${script_path%/*}"; this resolves symlinked script files, unlike cd "$(dirname ...)" && pwd, and stays portable across the repo's current macOS and Linux floor when used without GNU-only realpath flags
Prefer $() over backticks, and use case or arithmetic contexts where they improve clarity
In Zsh, follow Zsh expansion rules: do not quote ordinary scalar expansions just from Bash/POSIX habit; keep quotes where they preserve argv exactly, protect literal text, or are required by another shell or file format
Put reusable logic in functions, declare locals locally, and route top-level execution through main "$@"
In Zsh functions, start with emulate -L zsh and opt into options explicitly so caller settings do not leak into control flow
Check prerequisites with command -v, validate required environment variables, and clean up temporary files with traps
Prefer print -r -- in Zsh, keep help text in single quotes or heredocs, and support both short and long GNU-style options when a CLI is user-facing

Read references/operational-details.md for shell-specific safety details, CLI parsing, portability gotchas, toolchain choices, and cleanup patterns.

Common Mistakes

Picking a shell that the target environment does not reliably provide
Letting caller options leak into Zsh library behavior
Relying on interactive shell startup files in non-interactive contexts
Leaving variables unquoted or assuming the current working directory
Mixing normal output with diagnostics on stdout

name: developing-shell-scripts description: Use when writing or reviewing .sh, .bash, or .zsh files, Makefile shell snippets, CI shell commands, or choosing between Zsh, Bash, and POSIX sh in this repo.