Bash Pro Agent Skill

Use this skill when

• Writing or reviewing Bash scripts for automation, CI/CD, or ops
• Hardening shell scripts for safety and portability

Do not use this skill when

• You need POSIX-only shell without Bash features
• The task requires a higher-level language for complex logic
• You need Windows-native scripting (PowerShell)

Instructions

• Define script inputs, outputs, and failure modes.
• Apply strict mode and safe argument parsing.
• Implement core logic with defensive patterns.
• Add tests and linting with Bats and ShellCheck.

Safety

• Treat input as untrusted; avoid eval and unsafe globbing.
• Prefer dry-run modes before destructive actions.

Focus Areas

• Defensive programming with strict error handling
• POSIX compliance and cross-platform portability
• Safe argument parsing and input validation
• Robust file operations and temporary resource management
• Process orchestration and pipeline safety
• Production-grade logging and error reporting
• Comprehensive testing with Bats framework
• Static analysis with ShellCheck and formatting with shfmt
• Modern Bash 5.x features and best practices
• CI/CD integration and automation workflows

Approach

• Always use strict mode with set -Eeuo pipefail and proper error trapping
• Quote all variable expansions to prevent word splitting and globbing issues
• Prefer arrays and proper iteration over unsafe patterns like for f in $(ls)
• Use [[ ]] for Bash conditionals, fall back to [ ] for POSIX compliance
• Implement comprehensive argument parsing with getopts and usage functions
• Create temporary files and directories safely with mktemp and cleanup traps
• Prefer printf over echo for predictable output formatting
• Use command substitution $() instead of backticks for readability
• Implement structured logging with timestamps and configurable verbosity
• Design scripts to be idempotent and support dry-run modes
• Use shopt -s inherit_errexit for better error propagation in Bash 4.4+
• Employ IFS=$'\n\t' to prevent unwanted word splitting on spaces
• Validate inputs with : "${VAR:?message}" for required environment variables
• End option parsing with -- and use rm -rf -- "$dir" for safe operations
• Support --trace mode with set -x opt-in for detailed debugging
• Use xargs -0 with NUL boundaries for safe subprocess orchestration
• Employ readarray/mapfile for safe array population from command output
• Implement robust script directory detection: SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
• Use NUL-safe patterns: find -print0 | while IFS= read -r -d '' file; do ...; done

Compatibility & Portability

• Use #!/usr/bin/env bash shebang for portability across systems
• Check Bash version at script start: (( BASH_VERSINFO[0] >= 4 && BASH_VERSINFO[1] >= 4 )) for Bash 4.4+ features
• Validate required external commands exist: command -v jq &>/dev/null || exit 1
• Detect platform differences: case "$(uname -s)" in Linux*) ... ;; Darwin*) ... ;; esac
• Handle GNU vs BSD tool differences (e.g., sed -i vs sed -i '')
• Test scripts on all target platforms (Linux, macOS, BSD variants)
• Document minimum version requirements in script header comments
• Provide fallback implementations for platform-specific features
• Use built-in Bash features over external commands when possible for portability
• Avoid bashisms when POSIX compliance is required, document when using Bash-specific features

Readability & Maintainability

• Use long-form options in scripts for clarity: --verbose instead of -v
• Employ consistent naming: snake_case for functions/variables, UPPER_CASE for constants
• Add section headers with comment blocks to organize related functions
• Keep functions under 50 lines; refactor larger functions into smaller components
• Group related functions together with descriptive section headers
• Use descriptive function names that explain purpose: validate_input_file not check_file
• Add inline comments for non-obvious logic, avoid stating the obvious
• Maintain consistent indentation (2 or 4 spaces, never tabs mixed with spaces)
• Place opening braces on same line for consistency: function_name() {
• Use blank lines to separate logical blocks within functions
• Document function parameters and return values in header comments
• Extract magic numbers and strings to named constants at top of script

Safety & Security Patterns

• Declare constants with readonly to prevent accidental modification
• Use local keyword for all function variables to avoid polluting global scope
• Implement timeout for external commands: timeout 30s curl ... prevents hangs
• Validate file permissions before operations: [[ -r "$file" ]] || exit 1
• Use process substitution <(command) instead of temporary files when possible
• Sanitize user input before using in commands or file operations
• Validate numeric input with pattern matching: [[ $num =~ ^[0-9]+$ ]]
• Never use eval on user input; use arrays for dynamic command construction
• Set restrictive umask for sensitive operations: (umask 077; touch "$secure_file")
• Log security-relevant operations (authentication, privilege changes, file access)
• Use -- to separate options from arguments: rm -rf -- "$user_input"
• Validate environment variables before using: : "${REQUIRED_VAR:?not set}"
• Check exit codes of all security-critical operations explicitly
• Use trap to ensure cleanup happens even on abnormal exit

Performance Optimization

• Avoid subshells in loops; use while read instead of for i in $(cat file)
• Use Bash built-ins over external commands: [[ ]] instead of test, ${var//pattern/replacement} instead of sed
• Batch operations instead of repeated single operations (e.g., one sed with multiple expressions)
• Use mapfile/readarray for efficient array population from command output
• Avoid repeated command substitutions; store result in variable once
• Use arithmetic expansion $(( )) instead of expr for calculations
• Prefer printf over echo for formatted output (faster and more reliable)
• Use associative arrays for lookups instead of repeated grepping
• Process files line-by-line for large files instead of loading entire file into memory
• Use xargs -P for parallel processing when operations are independent

Documentation Standards

• Implement --help and -h flags showing usage, options, and examples
• Provide --version flag displaying script version and copyright information
• Include usage examples in help output for common use cases
• Document all command-line options with descriptions of their purpose
• List required vs optional arguments clearly in usage message
• Document exit codes: 0 for success, 1 for general errors, specific codes for specific failures
• Include prerequisites section listing required commands and versions
• Add header comment block with script purpose, author, and modification date
• Document environment variables the script uses or requires
• Provide troubleshooting section in help for common issues
• Generate documentation with shdoc from special comment formats
• Create man pages using shellman for system integration
• Include architecture diagrams using Mermaid or GraphViz for complex scripts

Modern Bash Features (5.x)

• Bash 5.0: Associative array improvements, ${var@U} uppercase conversion, ${var@L} lowercase
• Bash 5.1: Enhanced ${parameter@operator} transformations, compat shopt options for compatibility
• Bash 5.2: varredir_close option, improved exec error handling, EPOCHREALTIME microsecond precision
• Check version before using modern features: [[ ${BASH_VERSINFO[0]} -ge 5 && ${BASH_VERSINFO[1]} -ge 2 ]]
• Use ${parameter@Q} for shell-quoted output (Bash 4.4+)
• Use ${parameter@E} for escape sequence expansion (Bash 4.4+)
• Use ${parameter@P} for prompt expansion (Bash 4.4+)
• Use ${parameter@A} for assignment format (Bash 4.4+)
• Employ wait -n to wait for any background job (Bash 4.3+)
• Use mapfile -d delim for custom delimiters (Bash 4.4+)

CI/CD Integration

• GitHub Actions: Use shellcheck-problem-matchers for inline annotations
• Pre-commit hooks: Configure .pre-commit-config.yaml with shellcheck, shfmt, checkbashisms
• Matrix testing: Test across Bash 4.4, 5.0, 5.1, 5.2 on Linux and macOS
• Container testing: Use official bash:5.2 Docker images for reproducible tests
• CodeQL: Enable shell script scanning for security vulnerabilities
• Actionlint: Validate GitHub Actions workflow files that use shell scripts
• Automated releases: Tag versions and generate changelogs automatically
• Coverage reporting: Track test coverage and fail on regressions
• Example workflow: shellcheck *.sh && shfmt -d *.sh && bats test/

Security Scanning & Hardening

• SAST: Integrate Semgrep with custom rules for shell-specific vulnerabilities
• Secrets detection: Use gitleaks or trufflehog to prevent credential leaks
• Supply chain: Verify checksums of sourced external scripts
• Sandboxing: Run untrusted scripts in containers with restricted privileges
• SBOM: Document dependencies and external tools for compliance
• Security linting: Use ShellCheck with security-focused rules enabled
• Privilege analysis: Audit scripts for unnecessary root/sudo requirements
• Input sanitization: Validate all external inputs against allowlists
• Audit logging: Log all security-relevant operations to syslog
• Container security: Scan script execution environments for vulnerabilities

Observability & Logging

• Structured logging: Output JSON for log aggregation systems
• Log levels: Implement DEBUG, INFO, WARN, ERROR with configurable verbosity
• Syslog integration: Use logger command for system log integration
• Distributed tracing: Add trace IDs for multi-script workflow correlation
• Metrics export: Output Prometheus-format metrics for monitoring
• Error context: Include stack traces, environment info in error logs
• Log rotation: Configure log file rotation for long-running scripts
• Performance metrics: Track execution time, resource usage, external call latency
• Example: log_info() { logger -t "$SCRIPT_NAME" -p user.info "$*"; echo "[INFO] $*" >&2; }

Quality Checklist

• Scripts pass ShellCheck static analysis with minimal suppressions
• Code is formatted consistently with shfmt using standard options
• Comprehensive test coverage with Bats including edge cases
• All variable expansions are properly quoted
• Error handling covers all failure modes with meaningful messages
• Temporary resources are cleaned up properly with EXIT traps
• Scripts support --help and provide clear usage information
• Input validation prevents injection attacks and handles edge cases
• Scripts are portable across target platforms (Linux, macOS)
• Performance is adequate for expected workloads and data sizes

Output

• Production-ready Bash scripts with defensive programming practices
• Comprehensive test suites using bats-core or shellspec with TAP output
• CI/CD pipeline configurations (GitHub Actions, GitLab CI) for automated testing
• Documentation generated with shdoc and man pages with shellman
• Structured project layout with reusable library functions and dependency management
• Static analysis configuration files (.shellcheckrc, .shfmt.toml, .editorconfig)
• Performance benchmarks and profiling reports for critical workflows
• Security review with SAST, secrets scanning, and vulnerability reports
• Debugging utilities with trace modes, structured logging, and observability
• Migration guides for Bash 3→5 upgrades and legacy modernization
• Package distribution configurations (Homebrew formulas, deb/rpm specs)
• Container images for reproducible execution environments

Essential Tools

🧠 Knowledge Modules (Fractal Skills)

1. Static Analysis & Formatting

2. Testing Frameworks

3. Modern Development Tools

4. CI/CD & Automation

5. Style Guides & Best Practices

6. Tools & Frameworks

7. Security & Advanced Topics