posix-shell-pro

Use this skill when

Working on posix shell pro tasks or workflows
Needing guidance, best practices, or checklists for posix shell pro

Do not use this skill when

The task is unrelated to posix shell pro
You need a different domain or tool outside this scope

Instructions

Clarify goals, constraints, and required inputs.
Apply relevant best practices and validate outcomes.
Provide actionable steps and verification.
If detailed examples are required, open
```
resources/implementation-playbook.md
```
.

Focus Areas

Strict POSIX compliance for maximum portability
Shell-agnostic scripting that works on any Unix-like system
Defensive programming with portable error handling
Safe argument parsing without bash-specific features
Portable file operations and resource management
Cross-platform compatibility (Linux, BSD, Solaris, AIX, macOS)
Testing with dash, ash, and POSIX mode validation
Static analysis with ShellCheck in POSIX mode
Minimalist approach using only POSIX-specified features
Compatibility with legacy systems and embedded environments

POSIX Constraints

No arrays (use positional parameters or delimited strings)
No
```
[[
```
conditionals (use
```
[
```
test command only)
No process substitution
```
<()
```
or
```
>()
```
No brace expansion
```
{1..10}
```
No
```
local
```
keyword (use function-scoped variables carefully)
No
```
declare
```
,
```
typeset
```
, or
```
readonly
```
for variable attributes
No
```
+=
```
operator for string concatenation
No
```
${var//pattern/replacement}
```
substitution
No associative arrays or hash tables
No
```
source
```
command (use
```
.
```
for sourcing files)

Approach

Always use
```
#!/bin/sh
```
shebang for POSIX shell
Use
```
set -eu
```
for error handling (no
```
pipefail
```
in POSIX)
Quote all variable expansions:
```
"$var"
```
never
```
$var
```
Use
```
[ ]
```
for all conditional tests, never
```
[[
```
Implement argument parsing with
```
while
```
and
```
case
```
(no
```
getopts
```
for long options)
Create temporary files safely with
```
mktemp
```
and cleanup traps
Use
```
printf
```
instead of
```
echo
```
for all output (echo behavior varies)
Use
```
. script.sh
```
instead of
```
source script.sh
```
for sourcing
Implement error handling with explicit
```
|| exit 1
```
checks
Design scripts to be idempotent and support dry-run modes
Use
```
IFS
```
manipulation carefully and restore original value
Validate inputs with
```
[ -n "$var" ]
```
and
```
[ -z "$var" ]
```
tests
End option parsing with
```
--
```
and use
```
rm -rf -- "$dir"
```
for safety
Use command substitution
```
$()
```
instead of backticks for readability
Implement structured logging with timestamps using
```
date
```
Test scripts with dash/ash to verify POSIX compliance

Compatibility & Portability

Use
```
#!/bin/sh
```
to invoke the system's POSIX shell
Test on multiple shells: dash (Debian/Ubuntu default), ash (Alpine/BusyBox), bash --posix
Avoid GNU-specific options; use POSIX-specified flags only
Handle platform differences:
```
uname -s
```
for OS detection
Use
```
command -v
```
instead of
```
which
```
(more portable)

Check for command availability:

command -v cmd >/dev/null 2>&1 || exit 1

Provide portable implementations for missing utilities
Use
```
[ -e "$file" ]
```
for existence checks (works on all systems)
Avoid
```
/dev/stdin
```
,
```
/dev/stdout
```
(not universally available)
Use explicit redirection instead of
```
&>
```
(bash-specific)

Readability & Maintainability

Use descriptive variable names in UPPER_CASE for exports, lower_case for locals
Add section headers with comment blocks for organization
Keep functions under 50 lines; extract complex logic
Use consistent indentation (spaces only, typically 2 or 4)
Document function purpose and parameters in comments
Use meaningful names:
```
validate_input
```
not
```
check
```
Add comments for non-obvious POSIX workarounds
Group related functions with descriptive headers
Extract repeated code into functions
Use blank lines to separate logical sections

Safety & Security Patterns

Quote all variable expansions to prevent word splitting
Validate file permissions before operations:
```
[ -r "$file" ] || exit 1
```
Sanitize user input before using in commands
Validate numeric input:
```
case $num in *[!0-9]*) exit 1 ;; esac
```
Never use
```
eval
```
on untrusted input
Use
```
--
```
to separate options from arguments:
```
rm -- "$file"
```

Validate required variables:

[ -n "$VAR" ] || { echo "VAR required" >&2; exit 1; }

Check exit codes explicitly:
```
cmd || { echo "failed" >&2; exit 1; }
```

Use

trap

for cleanup:

trap 'rm -f "$tmpfile"' EXIT INT TERM

Set restrictive umask for sensitive files:
```
umask 077
```
Log security-relevant operations to syslog or file
Validate file paths don't contain unexpected characters
Use full paths for commands in security-critical scripts:
```
/bin/rm
```
not
```
rm
```

Performance Optimization

Use shell built-ins over external commands when possible
Avoid spawning subshells in loops: use
```
while read
```
not
```
for i in $(cat)
```
Cache command results in variables instead of repeated execution
Use
```
case
```
for multiple string comparisons (faster than repeated
```
if
```
)
Process files line-by-line for large files
Use
```
expr
```
or
```
$(( ))
```
for arithmetic (POSIX supports
```
$(( ))
```
)
Minimize external command calls in tight loops
Use
```
grep -q
```
when you only need true/false (faster than capturing output)
Batch similar operations together
Use here-documents for multi-line strings instead of multiple echo calls

Documentation Standards

Implement
```
-h
```
flag for help (avoid
```
--help
```
without proper parsing)
Include usage message showing synopsis and options
Document required vs optional arguments clearly
List exit codes: 0=success, 1=error, specific codes for specific failures
Document prerequisites and required commands
Add header comment with script purpose and author
Include examples of common usage patterns
Document environment variables used by script
Provide troubleshooting guidance for common issues
Note POSIX compliance in documentation

Working Without Arrays

Since POSIX sh lacks arrays, use these patterns:

Positional Parameters:

set -- item1 item2 item3; for arg; do echo "$arg"; done

Delimited Strings:

items="a:b:c"; IFS=:; set -- $items; IFS=' '

Newline-Separated:

items="a\nb\nc"; while IFS= read -r item; do echo "$item"; done <<EOF

Counters:

i=0; while [ $i -lt 10 ]; do i=$((i+1)); done

Field Splitting: Use
```
cut
```
,
```
awk
```
, or parameter expansion for string splitting

Portable Conditionals

Use

[ ]

test command with POSIX operators:

File Tests:
```
[ -e file ]
```
exists,
```
[ -f file ]
```
regular file,
```
[ -d dir ]
```
directory

String Tests:

[ -z "$str" ]

empty,

[ -n "$str" ]

not empty,

[ "$a" = "$b" ]

equal

Numeric Tests:
```
[ "$a" -eq "$b" ]
```
equal,
```
[ "$a" -lt "$b" ]
```
less than

Logical:

[ cond1 ] && [ cond2 ]

AND,

[ cond1 ] || [ cond2 ]

Negation:
```
[ ! -f file ]
```
not a file
Pattern Matching: Use
```
case
```
not
```
[[ =~ ]]
```

CI/CD Integration

Matrix testing: Test across dash, ash, bash --posix, yash on Linux, macOS, Alpine
Container testing: Use alpine:latest (ash), debian:stable (dash) for reproducible tests
Pre-commit hooks: Configure checkbashisms, shellcheck -s sh, shfmt -ln posix
GitHub Actions: Use shellcheck-problem-matchers with POSIX mode
Cross-platform validation: Test on Linux, macOS, FreeBSD, NetBSD
BusyBox testing: Validate on BusyBox environments for embedded systems
Automated releases: Tag versions and generate portable distribution packages
Coverage tracking: Ensure test coverage across all POSIX shells

Example workflow:

shellcheck -s sh *.sh && shfmt -ln posix -d *.sh && checkbashisms *.sh

Embedded Systems & Limited Environments

BusyBox compatibility: Test with BusyBox's limited ash implementation
Alpine Linux: Default shell is BusyBox ash, not bash
Resource constraints: Minimize memory usage, avoid spawning excessive processes
Missing utilities: Provide fallbacks when common tools unavailable (
```
mktemp
```
,
```
seq
```
)
Read-only filesystems: Handle scenarios where
```
/tmp
```
may be restricted
No coreutils: Some environments lack GNU coreutils extensions
Signal handling: Limited signal support in minimal environments
Startup scripts: Init scripts must be POSIX for maximum compatibility

Example: Check for mktemp:

command -v mktemp >/dev/null 2>&1 || mktemp() { ... }

Migration from Bash to POSIX sh

Assessment: Run
```
checkbashisms
```
to identify bash-specific constructs
Array elimination: Convert arrays to delimited strings or positional parameters
Conditional updates: Replace
```
[[
```
with
```
[
```
and adjust regex to
```
case
```
patterns
Local variables: Remove
```
local
```
keyword, use function prefixes instead
Process substitution: Replace
```
<()
```
with temporary files or pipes
Parameter expansion: Use
```
sed
```
/
```
awk
```
for complex string manipulation
Testing strategy: Incremental conversion with continuous validation
Documentation: Note any POSIX limitations or workarounds
Gradual migration: Convert one function at a time, test thoroughly
Fallback support: Maintain dual implementations during transition if needed

Quality Checklist

Scripts pass ShellCheck with
```
-s sh
```
flag (POSIX mode)
Code is formatted consistently with shfmt using
```
-ln posix
```
Test on multiple shells: dash, ash, bash --posix, yash
All variable expansions are properly quoted
No bash-specific features used (arrays,
```
[[
```
,
```
local
```
, etc.)
Error handling covers all failure modes
Temporary resources cleaned up with EXIT trap
Scripts provide clear usage information
Input validation prevents injection attacks
Scripts portable across Unix-like systems (Linux, BSD, Solaris, macOS, Alpine)
BusyBox compatibility validated for embedded use cases
No GNU-specific extensions or flags used

Output

POSIX-compliant shell scripts maximizing portability
Test suites using shellspec or bats-core validating across dash, ash, yash
CI/CD configurations for multi-shell matrix testing
Portable implementations of common patterns with fallbacks
Documentation on POSIX limitations and workarounds with examples
Migration guides for converting bash scripts to POSIX sh incrementally
Cross-platform compatibility matrices (Linux, BSD, macOS, Solaris, Alpine)
Performance benchmarks comparing different POSIX shells
Fallback implementations for missing utilities (mktemp, seq, timeout)
BusyBox-compatible scripts for embedded and container environments
Package distributions for various platforms without bash dependency

Essential Tools

Static Analysis & Formatting

ShellCheck: Static analyzer with
```
-s sh
```
for POSIX mode validation
shfmt: Shell formatter with
```
-ln posix
```
option for POSIX syntax
checkbashisms: Detects bash-specific constructs in scripts (from devscripts)
Semgrep: SAST with POSIX-specific security rules
CodeQL: Security scanning for shell scripts

POSIX Shell Implementations for Testing

dash: Debian Almquist Shell - lightweight, strict POSIX compliance (primary test target)
ash: Almquist Shell - BusyBox default, embedded systems
yash: Yet Another Shell - strict POSIX conformance validation
posh: Policy-compliant Ordinary Shell - Debian policy compliance
osh: Oil Shell - modern POSIX-compatible shell with better error messages
bash --posix: GNU Bash in POSIX mode for compatibility testing

Testing Frameworks

bats-core: Bash testing framework (works with POSIX sh)
shellspec: BDD-style testing that supports POSIX sh
shunit2: xUnit-style framework with POSIX sh support
sharness: Test framework used by Git (POSIX-compatible)

Common Pitfalls to Avoid

Using
```
[[
```
instead of
```
[
```
(bash-specific)
Using arrays (not in POSIX sh)
Using
```
local
```
keyword (bash/ksh extension)
Using
```
echo
```
without
```
printf
```
(behavior varies across implementations)
Using
```
source
```
instead of
```
.
```
for sourcing scripts
Using bash-specific parameter expansion:
```
${var//pattern/replacement}
```
Using process substitution
```
<()
```
or
```
>()
```
Using
```
function
```
keyword (ksh/bash syntax)
Using
```
$RANDOM
```
variable (not in POSIX)
Using
```
read -a
```
for arrays (bash-specific)
Using
```
set -o pipefail
```
(bash-specific)
Using
```
&>
```
for redirection (use
```
>file 2>&1
```
)

Advanced Techniques

Error Trapping:

trap 'echo "Error at line $LINENO" >&2; exit 1' EXIT; trap - EXIT

on success

Safe Temp Files:

tmpfile=$(mktemp) || exit 1; trap 'rm -f "$tmpfile"' EXIT INT TERM

Simulating Arrays:

set -- item1 item2 item3; for arg; do process "$arg"; done

Field Parsing:

IFS=:; while read -r user pass uid gid; do ...; done < /etc/passwd

String Replacement:
```
echo "$str" | sed 's/old/new/g'
```
or use parameter expansion
```
${str%suffix}
```
Default Values:
```
value=${var:-default}
```
assigns default if var unset or null
Portable Functions: Avoid
```
function
```
keyword, use
```
func_name() { ... }
```
Subshell Isolation:
```
(cd dir && cmd)
```
changes directory without affecting parent
Here-documents:
```
cat <<'EOF'
```
with quotes prevents variable expansion

Command Existence:

command -v cmd >/dev/null 2>&1 && echo "found" || echo "missing"

POSIX-Specific Best Practices

Always quote variable expansions:
```
"$var"
```
not
```
$var
```
Use
```
[ ]
```
with proper spacing:
```
[ "$a" = "$b" ]
```
not
```
["$a"="$b"]
```
Use
```
=
```
for string comparison, not
```
==
```
(bash extension)
Use
```
.
```
for sourcing, not
```
source
```
Use
```
printf
```
for all output, avoid
```
echo -e
```
or
```
echo -n
```
Use
```
$(( ))
```
for arithmetic, not
```
let
```
or
```
declare -i
```
Use
```
case
```
for pattern matching, not
```
[[ =~ ]]
```
Test scripts with
```
sh -n script.sh
```
to check syntax
Use
```
command -v
```
not
```
type
```
or
```
which
```
for portability
Explicitly handle all error conditions with
```
|| exit 1
```

References & Further Reading

POSIX Standards & Specifications

POSIX Shell Command Language - Official POSIX.1-2024 specification
POSIX Utilities - Complete list of POSIX-mandated utilities
Autoconf Portable Shell Programming - Comprehensive portability guide from GNU

Portability & Best Practices

Rich's sh (POSIX shell) tricks - Advanced POSIX shell techniques
Suckless Shell Style Guide - Minimalist POSIX sh patterns
FreeBSD Porter's Handbook - Shell - BSD portability considerations

Tools & Testing

checkbashisms - Detect bash-specific constructs