shell-guide
/shell-guide
Shell/Bash scripting guardrails, patterns, and best practices for AI-assisted development. Use when working with shell scripts (.sh, .bash), Makefiles, or when the user mentions Bash/Shell. Provides POSIX compliance guidelines, error handling patterns, and ShellCheck rules specific to this project's coding standards.
- Author
- ar4mirez ↗
- Repository
- samuel ↗
- Licence
- MIT
- Last repository change
- 29.04.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 8
No signals detected. Repository changed on 29.04.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Shell/Bash scripting guardrails, patterns, and best practices for AI-assisted development. Use when working with shell scripts (.sh, .bash), Makefiles, or when the user mentions Bash/Shell. Provides POSIX compliance guidelines, error handling patterns, and ShellCheck rules specific to this project's coding standards.
Original author description
Shell/Bash scripting guardrails, patterns, and best practices for AI-assisted development. Use when working with shell scripts (.sh, .bash), Makefiles, or when the user mentions Bash/Shell. Provides POSIX compliance guidelines, error handling patterns, and ShellCheck rules specific to this project's coding standards.
How it works
- Core Principles
- Guardrails
- Script Structure
- Key Patterns
- Testing
- Tooling
- References
- External References
SKILL.md preview
---
name: shell-guide
description: |
Shell/Bash scripting guardrails, patterns, and best practices for AI-assisted development.
Use when working with shell scripts (.sh, .bash), Makefiles, or when the user mentions Bash/Shell.
Provides POSIX compliance guidelines, error handling patterns, and ShellCheck rules
specific to this project's coding standards.
license: MIT
metadata:
author: samuel
version: "1.0"
category: language
language: shell
extensions: ".sh,.bash,.zsh"
---
# Shell/Bash Guide
> Applies to: Bash 4+, POSIX sh, Automation Scripts, CI/CD Pipelines, Makefiles
## Core Principles
1. **Strict Mode Always**: Every script starts with `set -euo pipefail` to fail fast on errors
2. **Quote Everything**: All variable expansions must be double-quoted to prevent word splitting and globbing
3. **Explicit Over Implicit**: Use `[[ ]]` for conditionals, `local` for function variables, named constants for magic values
4. **Fail Loudly**: Never swallow errors silently; use `trap` for cleanup and meaningful exit codes
5. **ShellCheck Clean**: All scripts pass `shellcheck` with zero warnings before commit
## Guardrails
### Shebang and Strict Mode
- Every script: `#!/usr/bin/env bash` (or `#!/bin/sh` for POSIX)
- Immediately follow with `set -euo pipefail`
- Use `set -x` only for debugging, never in production scripts
- POSIX scripts must not use bash-specific features (`[[ ]]`, arrays, `local`)
```bash
#!/usr/bin/env bash
set -euo pipefail
[[ "${TRACE:-}" == "1" ]] && set -x
```
### Quoting
- Always double-quote: `"$var"`, `"$@"`, `"${arr[@]}"`, `"$(command)"`
- Single quotes for literals that must not be interpolated
- Only omit quotes in arithmetic: `$(( count + 1 ))`
```bash
# Correct
grep -r "$pattern" "$directory"
for arg in "$@"; do process "$arg"; done
# Wrong - word splitting and globbing bugs
grep -r $pattern $directory
for arg in $@; do process $arg; done
```
### Error Handling
- Check return codes: `if ! command; then handle_error; fi`
- Inline: `critical_cmd || { echo "Failed" >&2; exit 1; }`
- Never use `set +e` (restructure logic instead)
- Exit codes: 0 = success, 1 = general error, 2 = usage error
- Errors to stderr: `echo "Error: message" >&2`
### Portability
- `#!/usr/bin/env bash` over `#!/bin/bash` (varies across systems)
- `command -v` instead of `which` for executable checks
- `$(command)` instead of backticks
- `printf` over `echo` for portable output (flags/escapes differ)
### Security
- Never use `eval` (use arrays for dynamic command building)
- Validate all external input (arguments, env vars, file contents)
- `mktemp` for temp files, never hardcoded `/tmp/myapp.tmp`
- No secrets in script files; read from environment or secret managers
- `umask 077` before creating sensitive files
```bash
# Safe temp file
tmpfile="$(mktemp)" || exit 1
trap 'rm -f "$tmpfile"' EXIT
# Never do this
eval "$user_input" # Command injection
password="hunter2" # Hardcoded secret
```
## Script Structure
```
#!/usr/bin/env bash
set -euo pipefail
readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly SCRIPT_NAME="$(basename "${BASH_SOURCE[0]}")"
# ── Configuration (with defaults) ─────────────────────
LOG_LEVEL="${LOG_LEVEL:-info}"
OUTPUT_DIR="${OUTPUT_DIR:-./output}"
# ── Functions ──────────────────────────────────────────
usage() { ... }
cleanup() { ... }
main() { ... }
# ── Traps & Entry ─────────────────────────────────────
trap cleanup EXIT
main "$@"
```
## Key Patterns
### Parameter Expansion
```bash
db_host="${DB_HOST:-localhost}" # Default value
api_key="${API_KEY:?Error: API_KEY required}" # Required (fail if unset)
filename="archive.tar.gz"
name="${filename%%.*}" # "archive" (longest suffix removal)
ext="${filename#*.}" # "tar.gz" (shortest prefix removal)
path="/usr/local/bin/tool"
dir="${path%/*}" # "/usr/local/bin"
base="${path##*/}" # "tool"
upper="${var^^}" # UPPERCASE (Bash 4+)
lower="${var,,}" # lowercase (Bash 4+)
```
### Trap for Cleanup
```bash
cleanup() {
local exit_code=$?
rm -f "$tmpfile"
exit "$exit_code" # Preserve original exit code
}
trap cleanup EXIT
trap 'echo "Interrupted" >&2; exit 130' INT TERM
```
### Arrays (Avoid eval)
```bash
declare -a files=()
files+=("first.txt" "second.txt")
for file in "${files[@]}"; do echo "$file"; done
# Build commands safely with arrays
cmd=(curl --silent --fail)
[[ -n "${TOKEN:-}" ]] && cmd+=(--header "Authorization: Bearer $TOKEN")
"${cmd[@]}" "$url"
```
### Functions
```bash
process_file() {
local file="$1"
local -r max_lines=1000
local line_count
line_count="$(wc -l < "$file")"
if (( line_count > max_lines )); then
echo "Warning: $file exceeds $max_lines lines" >&2
fi
}
```
All variables inside functions must be declared `local`.
### Here Documents
```bash
cat <<EOF # Interpolated
Hello, $USER at $(hostname)
EOF
cat <<'EOF' # Literal (no expansion)
This $variable stays literal.
EOF
```
### Safe File Iteration
```bash
# Handles spaces, newlines, special characters
while IFS= read -r -d '' file; do
process "$file"
done < <(find "$dir" -type f -name "*.log" -print0)
# Simple globs (Bash 4+)
shopt -s nullglob globstar
for file in "$dir"/**/*.sh; do process "$file"; done
```
Never use `for file in $(find ...)` -- it breaks on spaces.
### Process Substitution
```bash
diff <(sort file1.txt) <(sort file2.txt)
```
## Testing
### bats-core
```bash
# test/deploy.bats
setup() { export TMPDIR="$(mktemp -d)"; }
teardown() { rm -rf "$TMPDIR"; }
@test "deploy requires environment argument" {
run ./deploy.sh
[ "$status" -ne 0 ]
[[ "$output" == *"Usage:"* ]]
}
```
### Testing Standards
- Test with `bats-core` (preferred) or `shellspec`
- Test files in `test/` or `spec/` directory
- Test names describe behavior: `"deploy requires environment argument"`
- Use `setup`/`teardown` for temp dirs and fixtures
- Coverage: >80% library functions, >60% scripts
- Each test must be independent
## Tooling
### ShellCheck
```bash
shellcheck script.sh # Single file
find . -name "*.sh" -exec shellcheck {} + # All scripts
# Suppress with justification
# shellcheck disable=SC2034 # Variable used by sourced script
unused_looking_var="value"
```
### shfmt
```bash
shfmt -w -i 4 -bn script.sh # Format in place (4-space indent)
shfmt -d -i 4 script.sh # Check only (diff output)
```
### Essential Commands
```bash
shellcheck *.sh # Lint
shfmt -d -i 4 *.sh # Check formatting
bats test/ # Run tests
bash -n script.sh # Syntax check (no execution)
```
## References
For detailed patterns and examples, see:
- [references/patterns.md](references/patterns.md) -- Script templates, trap patterns, portable scripting examples
## External References
- [Bash Reference Manual](https://www.gnu.org/software/bash/manual/)
- [POSIX Shell Specification](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html)
- [ShellCheck Wiki](https://www.shellcheck.net/wiki/)
- [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html)
- [bats-core](https://github.com/bats-core/bats-core)
- [shellspec](https://shellspec.info/)
- [shfmt](https://github.com/mvdan/sh)
- [Pure Bash Bible](https://github.com/dylanaraps/pure-bash-bible)
Files in this package (2)
- SKILL.md 8 KB
- references/patterns.md 4 KB
Versions
The database has no other skills named shell-guide.
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version a08d3e1c85ec (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100bash
Expert Bash shell scripting assistance covering POSIX compliance, parameter expansion, pipelines, traps, and debugging. Use when writing robust shell scripts, automating DevOps tasks, or handling file processing. - 100shell
Shell scripting best practices for writing safe, portable, and maintainable bash/sh scripts. Use when writing, reviewing, or refactoring shell scripts, Dockerfile RUN commands, Makefile recipes, CI pipeline scripts, cron jobs, or systemd ExecStart directives. Triggers on bash,… - 90shell-scripting-guide
Use when writing or editing POSIX shell or Bash automation. Triggers on `.sh` files, `#!/usr/bin/env bash` shebangs, and prompts about scripting CI tasks, build helpers, devops automation, or one-off pipelines, even when the user doesn't say 'shell'. Apply for strict mode,… - 100shell-expert
Shell scripting expertise, command-line tools, automation, and cross-platform scripting best practices. Covers shell script development, CLI tool usage, and system automation with bash, zsh, and POSIX shell. Use when user mentions shell scripts, bash, zsh, CLI commands, pipes,… - 100shell
Shell scripting best practices and conventions for bash, sh, zsh, and other shells Triggers on: **/*.sh - 100shell-scripting
Bash, Zsh, POSIX sh, Fish scripts, one-liners, dotfiles, completions. Use for quoting or globbing bugs, shellcheck warnings, porting between shells.