Antigravity-awesome-skills 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 ]

  OR
• 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