playbooks

home / skills / pproenca / dot-skills / shell

shell skill

/skills/.experimental/shell

This skill helps you write portable, secure shell scripts by applying best practices for safety, error handling, quoting, and portability.

npx playbooks add skill pproenca/dot-skills --skill shell

Review the files below or copy the command above to add this skill to your agents.

Files (55)
SKILL.md
7.6 KB
---
name: shell
description: 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, sh, POSIX, ShellCheck, error handling, quoting, variables, set -euo pipefail.
---

# Shell Scripts Best Practices (Community)

Comprehensive best practices guide for shell scripting, designed for AI agents and LLMs. Contains 49 rules across 9 categories, prioritized by impact from critical (safety, portability) to incremental (style). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics.

## When to Apply

Reference these guidelines when:
- Writing new bash or POSIX shell scripts
- Reviewing shell scripts for security vulnerabilities
- Debugging scripts that fail silently or behave unexpectedly
- Porting scripts between Linux, macOS, and containers
- Optimizing shell script performance
- Setting up CI/CD pipelines with shell scripts

## Rule Categories by Priority

| Priority | Category | Impact | Prefix | Rules |
|----------|----------|--------|--------|-------|
| 1 | Safety & Security | CRITICAL | `safety-` | 6 |
| 2 | Portability | CRITICAL | `port-` | 5 |
| 3 | Error Handling | HIGH | `err-` | 8 |
| 4 | Variables & Data | HIGH | `var-` | 5 |
| 5 | Quoting & Expansion | MEDIUM-HIGH | `quote-` | 6 |
| 6 | Functions & Structure | MEDIUM | `func-` | 5 |
| 7 | Testing & Conditionals | MEDIUM | `test-` | 5 |
| 8 | Performance | LOW-MEDIUM | `perf-` | 6 |
| 9 | Style & Formatting | LOW | `style-` | 3 |

## Quick Reference

### 1. Safety & Security (CRITICAL)

- [`safety-command-injection`](references/safety-command-injection.md) - Prevent command injection from user input
- [`safety-eval-avoidance`](references/safety-eval-avoidance.md) - Avoid eval for dynamic commands
- [`safety-absolute-paths`](references/safety-absolute-paths.md) - Use absolute paths for external commands
- [`safety-temp-files`](references/safety-temp-files.md) - Create secure temporary files
- [`safety-suid-forbidden`](references/safety-suid-forbidden.md) - Never use SUID/SGID on shell scripts
- [`safety-argument-injection`](references/safety-argument-injection.md) - Prevent argument injection with double dash

### 2. Portability (CRITICAL)

- [`port-shebang-selection`](references/port-shebang-selection.md) - Choose shebang based on portability needs
- [`port-avoid-bashisms`](references/port-avoid-bashisms.md) - Avoid bashisms in POSIX scripts
- [`port-printf-over-echo`](references/port-printf-over-echo.md) - Use printf instead of echo for portability
- [`port-export-syntax`](references/port-export-syntax.md) - Use portable export syntax
- [`port-test-portability`](references/port-test-portability.md) - Use portable test constructs

### 3. Error Handling (HIGH)

- [`err-strict-mode`](references/err-strict-mode.md) - Use strict mode for error detection
- [`err-exit-codes`](references/err-exit-codes.md) - Use meaningful exit codes
- [`err-trap-cleanup`](references/err-trap-cleanup.md) - Use trap for cleanup on exit
- [`err-stderr-messages`](references/err-stderr-messages.md) - Send error messages to stderr
- [`err-pipefail`](references/err-pipefail.md) - Use pipefail to catch pipeline errors
- [`err-check-commands`](references/err-check-commands.md) - Check command success explicitly
- [`err-shellcheck`](references/err-shellcheck.md) - Use ShellCheck for static analysis
- [`err-debug-tracing`](references/err-debug-tracing.md) - Use debug tracing with set -x and PS4

### 4. Variables & Data (HIGH)

- [`var-use-arrays`](references/var-use-arrays.md) - Use arrays for lists instead of strings
- [`var-local-scope`](references/var-local-scope.md) - Use local for function variables
- [`var-naming-conventions`](references/var-naming-conventions.md) - Follow variable naming conventions
- [`var-readonly-constants`](references/var-readonly-constants.md) - Use readonly for constants
- [`var-default-values`](references/var-default-values.md) - Use parameter expansion for defaults

### 5. Quoting & Expansion (MEDIUM-HIGH)

- [`quote-always-quote-variables`](references/quote-always-quote-variables.md) - Always quote variable expansions
- [`quote-dollar-at`](references/quote-dollar-at.md) - Use "$@" for argument passing
- [`quote-command-substitution`](references/quote-command-substitution.md) - Quote command substitutions
- [`quote-brace-expansion`](references/quote-brace-expansion.md) - Use braces for variable clarity
- [`quote-here-documents`](references/quote-here-documents.md) - Use here documents for multi-line strings
- [`quote-glob-safety`](references/quote-glob-safety.md) - Control glob expansion explicitly

### 6. Functions & Structure (MEDIUM)

- [`func-main-pattern`](references/func-main-pattern.md) - Use main() function pattern
- [`func-single-purpose`](references/func-single-purpose.md) - Write single-purpose functions
- [`func-return-values`](references/func-return-values.md) - Use return values correctly
- [`func-documentation`](references/func-documentation.md) - Document functions with header comments
- [`func-avoid-aliases`](references/func-avoid-aliases.md) - Prefer functions over aliases

### 7. Testing & Conditionals (MEDIUM)

- [`test-double-brackets`](references/test-double-brackets.md) - Use [[ ]] for tests in bash
- [`test-arithmetic`](references/test-arithmetic.md) - Use (( )) for arithmetic comparisons
- [`test-explicit-empty`](references/test-explicit-empty.md) - Use explicit empty/non-empty string tests
- [`test-file-operators`](references/test-file-operators.md) - Use correct file test operators
- [`test-case-patterns`](references/test-case-patterns.md) - Use case for pattern matching

### 8. Performance (LOW-MEDIUM)

- [`perf-builtins-over-external`](references/perf-builtins-over-external.md) - Use builtins over external commands
- [`perf-avoid-subshells`](references/perf-avoid-subshells.md) - Avoid unnecessary subshells
- [`perf-process-substitution`](references/perf-process-substitution.md) - Use process substitution for temp files
- [`perf-read-files`](references/perf-read-files.md) - Read files efficiently
- [`perf-parameter-expansion`](references/perf-parameter-expansion.md) - Use parameter expansion for string operations
- [`perf-batch-operations`](references/perf-batch-operations.md) - Batch operations instead of loops

### 9. Style & Formatting (LOW)

- [`style-indentation`](references/style-indentation.md) - Use consistent indentation
- [`style-file-structure`](references/style-file-structure.md) - Follow consistent file structure
- [`style-comments`](references/style-comments.md) - Write useful comments


## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [AGENTS.md](AGENTS.md) | Complete compiled guide with all rules |
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |

## Key Sources

- [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html)
- [ShellCheck](https://www.shellcheck.net/)
- [Greg's Wiki (wooledge.org)](https://mywiki.wooledge.org/)
- [POSIX Shell Specification](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html)

Overview

This skill provides focused best practices for writing safe, portable, and maintainable shell (bash/sh/POSIX) scripts. It helps authors and reviewers harden scripts against injection, improve portability across environments, and adopt reliable error handling and testing patterns. Use it to raise script quality in CI, Dockerfiles, Makefiles, cron jobs, and systemd ExecStart directives.

How this skill works

The skill inspects shell code for common pitfalls and recommends prioritized rules across safety, portability, error handling, variables, quoting, structure, testing, performance, and style. It explains concrete fixes (e.g., quoting, parameter expansion, set -euo pipefail, secure temp files) and points to authoritative sources like ShellCheck and POSIX guidance. It outputs actionable suggestions, examples of incorrect vs correct patterns, and the expected impact of each change.

When to use it

  • Writing new shell scripts or Dockerfile RUN lines to ensure correct defaults and safety
  • Reviewing or refactoring existing scripts to remove security and portability issues
  • Hardening CI pipeline scripts, cron jobs, systemd ExecStart commands, and Makefile recipes
  • Debugging scripts that fail silently, mis-handle errors, or behave differently across OSes
  • Porting scripts between Linux, macOS, and container images to avoid bashisms

Best practices

  • Enable strict modes: set -euo pipefail and use explicit error trapping and cleanup
  • Always quote expansions and use "$@" for forwarding positional args to avoid word-splitting
  • Prefer portable constructs: choose shebangs carefully, avoid bashisms in POSIX scripts, and use printf over echo
  • Prevent injection: validate or avoid eval, use absolute command paths when needed, and handle user input safely
  • Use arrays and local variables in functions, document behavior, and return meaningful exit codes
  • Run ShellCheck and add tests that cover edge cases across target platforms

Example use cases

  • Refactoring a Dockerfile RUN block into reliable, debuggable shell commands that fail fast
  • Reviewing CI pipeline shell steps to catch silent failures and insecure temp file usage
  • Converting a macOS/bash script to POSIX-compliant sh for broader container compatibility
  • Hardening a cron job to log errors to stderr, set explicit PATH, and trap cleanup
  • Optimizing a script that spawns many subprocesses by replacing external calls with shell builtins

FAQ

Should I always use set -euo pipefail?

Yes for most scripts: it exposes failures early. Combine with traps for cleanup and be careful in contexts where partial failures are acceptable; handle those cases explicitly.

How do I choose between bash and POSIX sh?

Pick bash when you need bash-only features (arrays, [[ ]], (( ))). Choose POSIX sh for maximum portability across systems and containers; avoid bashisms and test on target platforms.