| name | internal-bash |
| description | Use when creating, analyzing, reviewing, or modifying embedded Bash or POSIX `sh`, sourced shell helpers, or non-operator shell fragments that need dialect, safety, quoting, parser, or validation guidance. |
Internal Bash
Referenced files
references/review-anti-patterns.md: Bash review anti-pattern catalog with
ID-tagged patterns, severity, rationale, and examples. Load for focused review
of shell content within this skill's scope.
When to use
- Review or modification of sourced
.sh helpers and Bash snippets where the
main need is a shared safety baseline.
- Shell embedded in repository automation when no narrower owner has stronger rules.
- Non-operator Bash helpers that do not own a standalone operator entrypoint.
- Quick checks for quoting, strict mode, guard clauses, temp files, and parser choices.
When not to use
- Standalone script design, standalone script review, launcher behavior,
operator UX, or script templates.
- Shell embedded in an automation format whose enclosing platform contract is
the primary subject.
- Workflow-level behavior beyond the shell fragment itself.
Dialect decision
Classify the shell before applying rules. Preserve an existing declared
interpreter and never silently change it. Record the declared interpreter, the
execution environment, and the compatibility target as the dialect contract:
Dialect: Bash when the caller, entrypoint, runtime, or repository contract
explicitly provides Bash.Dialect: POSIXsh`` when the caller or target requires POSIX shell syntax.
Require an explicit POSIX baseline before treating Issue 8 behavior as
portable. Do not infer portability from Bash invoked as sh.
Portable core
- Quote expansions and use explicit status checks at correctness boundaries.
- Prefer
if, case, test, and [ ] for shared control flow.
- Use
${parameter:?message} for required values and $((...)) for arithmetic.
- Use
mktemp with cleanup traps for temporary state.
- Validate required external commands with
command -v before first use.
- Use structured parsers such as
jq or yq for JSON and YAML when available.
Bash branch
For Dialect: Bash, use the repository shebang convention
#!/usr/bin/env bash, set -euo pipefail with documented exceptions, arrays
for dynamic commands, [[ ]], local, and Bash-specific traps or options.
POSIX sh branch
For Dialect: POSIXsh``, use the shebang convention declared by the target
repository or platform. Use set -eu with contextual -e caveats, scalar
variables and positional parameters, and [ ] or test. Do not use Bash arrays
or local. Use pipefail only when POSIX.1-2024 Issue 8 is an explicit
baseline; it is not a safe assumption for an unspecified /bin/sh.
File design
- Treat 300 lines as a review threshold for cohesive shell files.
- Treat 400 lines as a split-or-justify threshold and extract sourced helpers
when repeated decisions or branches degrade readability.
- Apply pragmatic DRY: de-duplicate repeated decision paths, but keep one-off
logic local when extraction harms auditability.
Validation
For Dialect: Bash, run bash -n <script>.sh and
shellcheck -s bash <script>.sh when available. For Dialect: POSIXsh``, run
sh -n <script>.sh, shellcheck -s sh <script>.sh, and execute under each
repository-supported sh implementation. Bash invoked as sh is not
cross-shell portability proof. Run the repository wrapper or focused command
when behavior changes.
