Shell Scripting Agent Skill

Shell Scripting

Purpose

Provides patterns and best practices for writing maintainable shell scripts with error handling, argument parsing, and portability considerations. Covers POSIX sh vs Bash decision-making, parameter expansion, integration with common utilities (jq, yq, awk), and testing with ShellCheck and Bats.

When to Use This Skill

Use shell scripting when:

• Orchestrating existing command-line tools and system utilities
• Writing CI/CD pipeline scripts (GitHub Actions, GitLab CI)
• Creating container entrypoints and initialization scripts
• Automating system administration tasks (backups, log rotation)
• Building development tooling (build scripts, test runners)

Consider Python/Go instead when:

• Complex business logic or data structures required
• Cross-platform GUI needed
• Heavy API integration (REST, gRPC)
• Script exceeds 200 lines with significant logic complexity

POSIX sh vs Bash

Use POSIX sh (#!/bin/sh) when:

• Maximum portability required (Linux, macOS, BSD, Alpine)
• Minimal container images needed
• Embedded systems or unknown target environments

Use Bash (#!/bin/bash) when:

• Controlled environment (specific OS, container)
• Arrays or associative arrays needed
• Advanced parameter expansion beneficial
• Process substitution <(cmd) useful

For detailed comparison and testing strategies, see references/portability-guide.md.

Essential Error Handling

Fail-Fast Pattern

#!/bin/bash
set -euo pipefail

# -e: Exit on error
# -u: Exit on undefined variable
# -o pipefail: Pipeline fails if any command fails

Use for production automation, CI/CD scripts, and critical operations.

Explicit Exit Code Checking

#!/bin/bash

if ! command_that_might_fail; then
    echo "Error: Command failed" >&2
    exit 1
fi

Use for custom error messages and interactive scripts.

Trap Handlers for Cleanup

#!/bin/bash
set -euo pipefail

TEMP_FILE=$(mktemp)

cleanup() {
    rm -f "$TEMP_FILE"
}

trap cleanup EXIT

Use for guaranteed cleanup of temporary files, locks, and resources.

For comprehensive error patterns, see references/error-handling.md.

Argument Parsing

Short Options with getopts (POSIX)

#!/bin/bash

while getopts "hvf:o:" opt; do
    case "$opt" in
        h) usage ;;
        v) VERBOSE=true ;;
        f) INPUT_FILE="$OPTARG" ;;
        o) OUTPUT_FILE="$OPTARG" ;;
        *) usage ;;
    esac
done

shift $((OPTIND - 1))

Long Options (Manual Parsing)

#!/bin/bash

while [[ $# -gt 0 ]]; do
    case "$1" in
        --help) usage ;;
        --verbose) VERBOSE=true; shift ;;
        --file) INPUT_FILE="$2"; shift 2 ;;
        --file=*) INPUT_FILE="${1#*=}"; shift ;;
        *) break ;;
    esac
done

For hybrid approaches and validation patterns, see references/argument-parsing.md.

Parameter Expansion Quick Reference

# Default values
${var:-default}              # Use default if unset
${var:=default}              # Assign default if unset
: "${API_KEY:?Error: required}"  # Error if unset

# String manipulation
${#var}                      # String length
${var:offset:length}         # Substring
${var%.txt}                  # Remove suffix
${var##*/}                   # Basename
${var/old/new}               # Replace first
${var//old/new}              # Replace all

# Case conversion (Bash 4+)
${var^^}                     # Uppercase
${var,,}                     # Lowercase

For complete expansion patterns and array handling, see references/parameter-expansion.md.

Common Utilities Integration

JSON with jq

# Extract field
name=$(curl -sSL https://api.example.com/user | jq -r '.name')

# Filter array
active=$(jq '.users[] | select(.active) | .name' data.json)

# Check existence
if ! echo "$json" | jq -e '.field' >/dev/null; then
    echo "Error: Field missing" >&2
fi

YAML with yq

# Read value (yq v4)
host=$(yq eval '.database.host' config.yaml)

# Update in-place
yq eval '.port = 5432' -i config.yaml

# Convert to JSON
yq eval -o=json config.yaml

Text Processing

# awk: Extract columns
awk -F',' '{print $1, $3}' data.csv

# sed: Replace text
sed 's/old/new/g' file.txt

# grep: Pattern match
grep -E "ERROR|WARN" logfile.txt

For detailed examples and best practices, see references/common-utilities.md.

Testing and Validation

ShellCheck: Static Analysis

# Check script
shellcheck script.sh

# POSIX compliance
shellcheck --shell=sh script.sh

# Exclude warnings
shellcheck --exclude=SC2086 script.sh

Bats: Automated Testing

#!/usr/bin/env bats

@test "script runs successfully" {
    run ./script.sh --help
    [ "$status" -eq 0 ]
    [ "${lines[0]}" = "Usage: script.sh [OPTIONS]" ]
}

@test "handles missing argument" {
    run ./script.sh
    [ "$status" -eq 1 ]
    [[ "$output" =~ "Error" ]]
}

Run tests:

bats test/

For CI/CD integration and debugging techniques, see references/testing-guide.md.

Defensive Programming Checklist

#!/bin/bash
set -euo pipefail

# Check required commands
command -v jq >/dev/null 2>&1 || {
    echo "Error: jq required" >&2
    exit 1
}

# Check environment variables
: "${API_KEY:?Error: API_KEY required}"

# Check files
[ -f "$CONFIG_FILE" ] || {
    echo "Error: Config not found: $CONFIG_FILE" >&2
    exit 1
}

# Quote all variables
echo "Processing: $file"        # ❌ Unquoted
echo "Processing: \"$file\""    # ✅ Quoted

Platform Considerations

macOS vs Linux Differences

# sed in-place
sed -i '' 's/old/new/g' file.txt    # macOS
sed -i 's/old/new/g' file.txt       # Linux

# Portable: Use temp file
sed 's/old/new/g' file.txt > file.txt.tmp
mv file.txt.tmp file.txt

# readlink
readlink -f /path                    # Linux only
cd "$(dirname "$0")" && pwd         # Portable

For complete platform differences, see references/portability-guide.md.

Script Categories

System Administration: Cron jobs, log rotation, backup automation

Build/Deployment: CI/CD pipelines, Docker builds, deployments

Development Tooling: Project setup, test runners, code generators

Container Entrypoints: Initialization, signal handling, configuration

Production Script Template

#!/bin/bash
set -euo pipefail

readonly SCRIPT_NAME="$(basename "$0")"
readonly SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"

TEMP_DIR=""

cleanup() {
    local exit_code=$?
    rm -rf "$TEMP_DIR"
    exit "$exit_code"
}

trap cleanup EXIT

log() {
    echo "[$(date +'%Y-%m-%d %H:%M:%S')] $*" >&2
}

main() {
    # Check dependencies
    command -v jq >/dev/null 2>&1 || exit 1

    # Parse arguments
    # Validate input
    # Process
    # Report results

    log "Completed successfully"
}

main "$@"

For complete production template, see examples/production-template.sh.

Tool Recommendations

Core Tools:

• jq: JSON parsing and transformation
• yq: YAML parsing (v4 recommended)
• ShellCheck: Static analysis and linting
• Bats: Automated testing framework

Installation:

# macOS
brew install jq yq shellcheck bats-core

# Ubuntu/Debian
apt-get install jq shellcheck

Related Skills

• linux-administration: System commands and administration
• building-ci-pipelines: Using scripts in CI/CD
• infrastructure-as-code: Terraform/Pulumi wrappers
• kubernetes-operations: kubectl scripts, Helm hooks
• writing-dockerfiles: Container entrypoints

Additional Resources

Reference Files:

• references/error-handling.md - Comprehensive error patterns
• references/argument-parsing.md - Advanced parsing techniques
• references/parameter-expansion.md - Complete expansion reference
• references/portability-guide.md - POSIX vs Bash differences
• references/testing-guide.md - ShellCheck and Bats guide
• references/common-utilities.md - jq, yq, awk, sed usage

Example Scripts:

• examples/production-template.sh - Production-ready template
• examples/getopts-basic.sh - Simple getopts usage
• examples/getopts-advanced.sh - Complex option handling
• examples/long-options.sh - Manual long option parsing
• examples/error-handling.sh - Error handling patterns
• examples/json-yaml-processing.sh - jq/yq examples

Utility Scripts:

• scripts/lint-script.sh - ShellCheck wrapper for CI
• scripts/test-script.sh - Bats wrapper for CI