/bash-script-validator

name: bash-script-validator
description: Validate, lint, audit, or fix bash/shell/.sh scripts via ShellCheck.

Bash Script Validator

Overview

This skill validates Bash and POSIX shell scripts with layered checks:

1. Syntax validation (`bash -n` or `sh -n`) 2. ShellCheck static analysis (system binary or wrapper fallback) 3. Custom security, portability, and optimization checks

Use the default flow below, then branch to fallbacks only when the environment is constrained.

Trigger Guidance

Use this skill when the request includes script quality, linting, syntax checking, or shell portability work.

Trigger Phrases

• "Validate this bash script"
• "Lint this `.sh` file"
• "Find security issues in this shell script"
• "Why does this script fail ShellCheck?"
• "Make this script POSIX compliant"
• "Review this shell script before CI"

Non-Trigger Examples

• General Linux command questions with no script file
• Kubernetes, Terraform, or pipeline validation tasks that do not involve shell scripts
• Pure prose editing tasks

Deterministic Execution Model

Run commands from this skill directory:

cd devops-skills-plugin/skills/bash-script-validator

Step 1: Preflight

1. Confirm target path exists and is readable. 2. Confirm `bash` is available. 3. Determine whether fixes can be applied directly (write access) or only suggested (read-only).

Step 2: Run Baseline Validation (Default Path)

bash scripts/validate.sh <script-path>

For deterministic stage behavior, set the ShellCheck provider explicitly:

# Modes: auto (default), system, wrapper, disabled
VALIDATOR_SHELLCHECK_MODE=system bash scripts/validate.sh <script-path>

Record:

• Detected shell type
• Exit code (`0` clean, `1` warnings, `2` errors)
• All reported issue lines and ShellCheck codes (`SC####`) when present

Step 3: Load Only Needed References

Progressive disclosure by issue type:

• ShellCheck code explanations: `docs/shellcheck-reference.md`
• General fix patterns and security mistakes: `docs/common-mistakes.md`
• Bash-only behavior: `docs/bash-reference.md`
• POSIX portability or bashism fixes: `docs/shell-reference.md`
• Text-processing optimization issues: `docs/grep-reference.md`, `docs/awk-reference.md`, `docs/sed-reference.md`, `docs/regex-reference.md` (only when directly relevant)

Step 4: Provide or Apply Fixes

For each issue, include:

1. Exact location from validator output (line number and snippet) 2. Root cause 3. Corrected code 4. Why the change is safer or more portable 5. Subsection-level citation (format below)

If the request includes patching files and write access is available, apply fixes in small batches grouped by issue type.

Step 5: Rerun Policy (Mandatory After Changes)

After each batch of edits, rerun the validator:

bash scripts/validate.sh <script-path>

Rerun loop rules:

1. Continue until no new errors are introduced. 2. If warnings remain by design, document why they are intentionally accepted. 3. If constraints prevent full resolution, report unresolved items with a clear next action. 4. Always report the latest rerun exit code and remaining issue count.

Fallback Behavior

Use these branches only when the default flow cannot run as-is.

| Constraint | Fallback action | Reporting requirement | | --- | --- | --- | | `shellcheck` missing, wrapper available | Let `scripts/validate.sh` use `scripts/shellcheck_wrapper.sh --cache` automatically | State that wrapper mode was used | | `shellcheck` and wrapper unavailable | Run syntax + custom checks only (validator does this) | Explicitly call out reduced coverage and missing ShellCheck analysis | | Python unavailable for wrapper | Skip wrapper path, keep syntax + custom checks | State why ShellCheck could not run | | Target file is read-only | Provide precise patch suggestions without editing | Mark response as "advisory only" | | Target file missing or unreadable | Stop and request a valid file path | Do not fabricate results | | Binary/non-text input | Stop validation | Report unsupported input type |

Citation Guidance for Fixes

Use subsection-level citations for every non-trivial fix.

Required citation format:

Reference: docs/<file>.md -> <Section> -> <Subsection>

Examples:

• `Reference: docs/common-mistakes.md -> 1. Unquoted Variables -> Solution`
• `Reference: docs/shellcheck-reference.md -> SC2164: Use || exit After cd`
• `Reference: docs/shell-reference.md -> POSIX Best Practices -> 5. Avoid Bashisms`

Citation rules:

1. Cite the most specific section that justifies the fix. 2. For ShellCheck findings, include both the `SC####` code and the matching section. 3. If no exact subsection exists, cite the closest section and state that the fix is inferred from that guidance.

Response Template

Use this structure for deterministic output:

• `Validation Results`
• `Command`: `bash scripts/validate.sh <script-path>`
• `Detected shell`: `<shell>`
• `Exit code`: `<code>`
• `Summary`: `<errors> errors, <warnings> warnings, <info> info`
• `Issue`: `<short label> (Line <n>)`
• `Problem`:

  <problematic snippet>

• `Fix`:

  <corrected snippet>

• `Why`: `<short explanation>`
• `Reference`: `docs/<file>.md -> <Section> -> <Subsection>`
• `Rerun command`: `bash scripts/validate.sh <script-path>`
• `Exit code after fixes`: `<code>`
• `Remaining issues`: `<count or none>`

Example Flows

Fully Automated Environment

# 1) Baseline validation
bash scripts/validate.sh examples/bad-bash.sh

# 2) Apply fixes to target script
# 3) Rerun validation
bash scripts/validate.sh examples/bad-bash.sh

Expected behavior: full syntax + ShellCheck + custom-check coverage, with iterative reruns until stable.

Deterministic CI Gate

# Requires a system shellcheck binary.
bash scripts/run_ci_checks.sh

This runner enforces `VALIDATOR_REQUIRE_SHELLCHECK=1` and `VALIDATOR_SHELLCHECK_MODE=sys