# Bash Style Guide

> Style, review, and refactoring standards for Bash shell scripting. Trigger when `.sh` files, files with `#!/usr/bin/env bash` or `#!/bin/bash`, or CI workflow blocks with `shell: bash` are created, modified, or reviewed and Bash-specific quality controls (quoting safety, error handling, portability, readability) must be enforced. Do not use for generic POSIX `sh`, PowerShell, or language-specific…

- **Type:** Skill
- **Install:** `agentstack add skill-kentoshimizu-sw-agent-skills-bash-style-guide`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [KentoShimizu](https://agentstack.voostack.com/s/kentoshimizu)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [KentoShimizu](https://github.com/KentoShimizu)
- **Source:** https://github.com/KentoShimizu/sw-agent-skills/tree/main/skills/bash-style-guide

## Install

```sh
agentstack add skill-kentoshimizu-sw-agent-skills-bash-style-guide
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Bash Style Guide

## Scope Boundaries
- Use this skill when the task matches the trigger condition described in `description`.
- Do not use this skill when the primary task falls outside this skill's domain.

Use this skill to write and review Bash scripts that are safe, debuggable, and operable in CI and production automation.

## Trigger And Co-activation Reference

- If available, use `references/trigger-matrix.md` for canonical co-activation rules.
- If available, resolve style-guide activation from changed files with `python3 scripts/resolve_style_guides.py ...`.
- If available, validate trigger matrix consistency with `python3 scripts/validate_trigger_matrix_sync.py`.

## Quality Gate Command Reference

- If available, use `references/quality-gate-command-matrix.md` for CI check-only and local autofix mapping.

## Quick Start Snippets

### Script skeleton with strict mode and cleanup trap

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

readonly SCRIPT_NAME="$(basename "$0")"
readonly TEMP_DIR="$(mktemp -d)"

cleanup() {
  rm -rf -- "${TEMP_DIR}"
}

on_error() {
  local line="$1"
  local exit_code="$2"
  echo "${SCRIPT_NAME}: failed at line ${line} (exit=${exit_code})" >&2
}

trap cleanup EXIT
trap 'on_error "$LINENO" "$?"' ERR

main() {
  echo "working dir: ${TEMP_DIR}"
}

main "$@"
```

### Required environment variable check (fail fast)

```bash
: "${API_TOKEN:?API_TOKEN is required}"
: "${API_BASE_URL:?API_BASE_URL is required}"
```

### Safe command assembly with arrays

```bash
run_curl() {
  local url="$1"
  local -a args=(
    --fail
    --silent
    --show-error
    --header "Authorization: Bearer ${API_TOKEN}"
    "${url}"
  )

  curl "${args[@]}"
}
```

### Bounded retry with explicit backoff constants

```bash
readonly MAX_ATTEMPTS=5
readonly RETRY_DELAY_SECONDS=2

retry_command() {
  local attempt=1
  while (( attempt &2
      return 1
    fi

    sleep "${RETRY_DELAY_SECONDS}"
    ((attempt++))
  done
}
```

### Safe line reading preserving whitespace

```bash
while IFS= read -r line; do
  printf 'line=%s\n' "${line}"
done < "${input_file}"
```

## Structure And Readability

1. Use `#!/usr/bin/env bash` for executable scripts.
2. For executable entrypoints, use strict mode: `set -euo pipefail`.
3. Keep functions focused on one responsibility and use `main` for orchestration.
4. Use uppercase constants (`MAX_RETRIES`) and lowercase locals (`retry_count`).
5. Use `local` inside functions to avoid state leakage.
6. Add short intent comments only for non-obvious logic.

## Data Handling And Quoting

1. Quote expansions by default: `"${var}"`, `"${array[@]}"`.
2. Use arrays for argument lists; avoid string-concatenated command assembly.
3. Replace magic numbers with named constants including units (`TIMEOUT_SECONDS`).
4. Avoid `eval`; treat it as a security-sensitive last resort.
5. Fail fast for required environment variables; do not add silent defaults for required config.

## Error Handling And Control Flow

1. Return explicit non-zero codes for expected failure modes.
2. Use `trap` for cleanup and actionable error reporting.
3. Handle failure paths intentionally (`if ! cmd; then ... fi`) instead of masking.
4. Avoid broad `|| true`; suppress only with explicit rationale.
5. Let failures surface when root cause should be fixed.

## Security And Operational Safety

1. Validate all external input before use.
2. Use `--` before positional paths in destructive commands (`rm -- "$target"`).
3. Prefer `mktemp` for temporary files/directories.
4. Never print secrets or tokens in logs.
5. Use least privilege and avoid unnecessary `sudo`.

## Performance And Scalability

1. Avoid subshell spawning in tight loops when builtins suffice.
2. Prefer single-pass text processing over repeated pipelines.
3. Batch filesystem operations where practical.
4. Use bounded retry loops with named backoff constants.

## Testing And Verification

1. Add `bats` tests for critical behavior and failure paths.
2. Cover edge cases: empty input, whitespace paths, missing env vars, timeout, retry exhaustion.
3. Document manual verification where automation is not feasible.
4. Check idempotency for scripts that may run repeatedly.

### Minimal `bats` example

```bash
#!/usr/bin/env bats

@test "fails when required env var is missing" {
  run ./script.sh
  [ "$status" -ne 0 ]
  [[ "$output" == *"API_TOKEN is required"* ]]
}
```

## CI Required Quality Gates (check-only)

1. Run `shellcheck` with warnings treated as actionable.
2. Run `shfmt -d` (or equivalent check mode) and require zero diff.
3. Run test suite (`bats test/` or repository-specific path).
4. Reject changes that hide failures or rely on implicit behavior.

## Optional Autofix Commands (local)

1. Run `shfmt -w`.
2. Apply safe mechanical fixes suggested by `shellcheck`, then rerun checks.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [KentoShimizu](https://github.com/KentoShimizu)
- **Source:** [KentoShimizu/sw-agent-skills](https://github.com/KentoShimizu/sw-agent-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-kentoshimizu-sw-agent-skills-bash-style-guide
- Seller: https://agentstack.voostack.com/s/kentoshimizu
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.