Shell Script Workflow Skill

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Shell Script Workflow

Tool Grid

| Task | Tool | Command | |------|------|---------| | Lint | shellcheck | shellcheck *.sh | | Format | shfmt | shfmt -w *.sh | | Coverage | bashcov | bashcov ./test.sh |

Shebang

Scripts MUST use the portable shebang:

#!/usr/bin/env bash

POSIX-only scripts MAY use #!/bin/sh when bash features are not needed.

Strict Mode

All bash scripts MUST enable strict mode at the top:

set -euo pipefail

| Flag | Meaning | |------|---------| | -e | Exit on error | | -u | Error on undefined variables | | -o pipefail | Fail on pipe errors |

For debugging, scripts MAY temporarily add set -x for trace output.

Size Limit

Scripts SHOULD NOT exceed 100 lines of code (excluding comments and blank lines).

When a script exceeds 100 lines:

The script SHOULD be refactored into smaller functions
Complex logic SHOULD be converted to Python for maintainability

Variable Quoting

Variables MUST be quoted to prevent word splitting and glob expansion:

# Correct
echo "$variable"
cp "$source" "$destination"

# Incorrect - MUST NOT use
echo $variable
cp $source $destination

Arrays MUST use proper expansion:

# Correct
"${array[@]}"

# For single string with spaces
"${array[*]}"

Variable Naming

| Scope | Convention | Example | |-------|------------|---------| | Environment/Global | UPPER_CASE | LOG_LEVEL, CONFIG_PATH | | Local/Script | lower_case | file_count, temp_dir | | Constants | UPPER_CASE | readonly MAX_RETRIES=3 |

Constants SHOULD be declared with readonly:

readonly CONFIG_FILE="/etc/app/config"
readonly -a VALID_OPTIONS=("start" "stop" "restart")

Test Syntax

In bash scripts, [[ ]] MUST be used over [ ]:

# Correct - bash
if [[ -f "$file" ]]; then
    echo "File exists"
fi

if [[ "$string" == "value" ]]; then
    echo "Match"
fi

# Pattern matching (bash-only)
if [[ "$string" =~ ^[0-9]+$ ]]; then
    echo "Numeric"
fi

POSIX scripts MUST use [ ] for compatibility.

Functions

Functions MUST use local for internal variables:

my_function() {
    local input="$1"
    local result=""

    # Process input
    result=$(process "$input")

    echo "$result"
}

Function naming conventions:

Use snake_case: process_file, validate_input
Prefix private functions with underscore: _helper_function

Temporary Files

Temporary files MUST be created with mktemp:

temp_file=$(mktemp)
temp_dir=$(mktemp -d)

Cleanup MUST be ensured with trap:

cleanup() {
    rm -f "$temp_file"
    rm -rf "$temp_dir"
}
trap cleanup EXIT

The EXIT trap ensures cleanup runs on normal exit, error, or interrupt.

Exit Codes

Scripts MUST use standard exit codes:

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error | | 2 | Misuse (invalid arguments, missing dependencies) |

Example usage:

main() {
    if [[ $# -lt 1 ]]; then
        echo "Usage: $0 <argument>" >&2
        exit 2
    fi

    if ! process_data "$1"; then
        echo "Error: Processing failed" >&2
        exit 1
    fi

    exit 0
}

Error Handling

Continuing on Error

Use || true when a command failure SHOULD NOT stop execution:

rm -f "$optional_file" || true

Explicit Failure

Use || exit 1 for critical operations:

cd "$required_dir" || exit 1
source "$config_file" || exit 1

Custom Error Messages

command_that_might_fail || {
    echo "Error: command failed" >&2
    exit 1
}

Portability Considerations

POSIX vs Bash

| Feature | POSIX | Bash | |---------|-------|------| | Test syntax | [ ] | [[ ]] | | Arrays | Not available | Supported | | local | Not standard | Supported | | source | Use . | Both work | | Process substitution | Not available | <(cmd) |

Portable Alternatives

When POSIX compatibility is REQUIRED:

# Instead of bash arrays, use positional parameters or newline-separated strings
files=$(find . -name "*.txt")

# Instead of [[ ]], use [ ]
if [ -f "$file" ]; then
    echo "exists"
fi

# Instead of source, use .
. ./config.sh

Input Validation

User input MUST be validated:

validate_input() {
    local input="$1"

    if [[ -z "$input" ]]; then
        echo "Error: Input cannot be empty" >&2
        return 1
    fi

    if [[ ! "$input" =~ ^[a-zA-Z0-9_-]+$ ]]; then
        echo "Error: Invalid characters in input" >&2
        return 1
    fi

    return 0
}

Command Substitution

Modern syntax MUST be used:

# Correct
result=$(command)
nested=$(echo $(inner_command))

# Incorrect - MUST NOT use backticks
result=`command`

Logging

Scripts SHOULD include consistent logging:

log_info() {
    echo "[INFO] $*"
}

log_error() {
    echo "[ERROR] $*" >&2
}

log_debug() {
    [[ "${DEBUG:-0}" == "1" ]] && echo "[DEBUG] $*"
}

Script Template

#!/usr/bin/env bash
set -euo pipefail

readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly SCRIPT_NAME="$(basename "$0")"

usage() {
    cat <<EOF
Usage: $SCRIPT_NAME [options] <argument>

Options:
    -h, --help    Show this help message
    -v, --verbose Enable verbose output

EOF
}

main() {
    local verbose=0

    while [[ $# -gt 0 ]]; do
        case "$1" in
            -h|--help)
                usage
                exit 0
                ;;
            -v|--verbose)
                verbose=1
                shift
                ;;
            *)
                break
                ;;
        esac
    done

    if [[ $# -lt 1 ]]; then
        usage >&2
        exit 2
    fi

    # Script logic here
}

main "$@"

Agent Skills: Shell Script Workflow

Install this agent skill to your local

Skill Files