shell-script-reviewer
/shell-script-reviewer
Reviews Bash, Zsh, and Fish shell scripts for bugs, security vulnerabilities, portability issues, and style violations against the Google Shell Style Guide, ShellCheck, BashPitfalls, and shell-specific idiom conventions. Use when the user asks to review, audit, lint, or improve a .sh/.bash/.zsh/.fish file, or pastes shell script content for feedback.
- Author
- rikdc ↗
- Repository
- claude_code_template ↗
- Licence
- MPL-2.0
- Last repository change
- 22.10.2026
Assessment and security
- Files in this package
- 11
- Scripts
- 3
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.
MPL-2.0, otwarta.
- 3 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/detect_shell.sh, scripts/run_shellcheck.sh, scripts/run_shfmt_check.sh
What it does and when to use it
Reviews Bash, Zsh, and Fish shell scripts for bugs, security vulnerabilities, portability issues, and style violations against the Google Shell Style Guide, ShellCheck, BashPitfalls, and shell-specific idiom conventions. Use when the user asks to review, audit, lint, or improve a .sh/.bash/.zsh/.fish file, or pastes shell script content for feedback.
Arguments
/shell-script-reviewer [file_or_dir] [--security] [--fix]
Original author description
Reviews Bash, Zsh, and Fish shell scripts for bugs, security vulnerabilities, portability issues, and style violations against the Google Shell Style Guide, ShellCheck, BashPitfalls, and shell-specific idiom conventions. Use when the user asks to review, audit, lint, or improve a .sh/.bash/.zsh/.fish file, or pastes shell script content for feedback.
How it works
- Reference files
- Step 1: Identify the dialect
- Step 2: Run static analysis first when possible
- Step 3: Apply manual review categories, in this priority order
- Step 4: Output format
- Step 5: Escalation rule
- Task execution
SKILL.md preview
---
name: shell-script-reviewer
description: Reviews Bash, Zsh, and Fish shell scripts for bugs, security vulnerabilities, portability issues, and style violations against the Google Shell Style Guide, ShellCheck, BashPitfalls, and shell-specific idiom conventions. Use when the user asks to review, audit, lint, or improve a .sh/.bash/.zsh/.fish file, or pastes shell script content for feedback.
user-invocable: true
argument-hint: "[file_or_dir] [--security] [--fix]"
allowed-tools: Read, Glob, Grep, Bash(shellcheck:*), Bash(shfmt:*), Bash(fish:*), Bash(git diff:*), Bash(git log:*), Bash(find:*)
---
# Shell Script Reviewer
You are a **shell script reviewer** grounded in named authorities rather
than ad-hoc opinion: the Google Shell Style Guide for structure, ShellCheck
for static analysis, Greg's Wiki BashPitfalls for defensive scripting, and
a dedicated security checklist. Bash, Zsh, and Fish diverge meaningfully in
syntax and semantics — never apply a Bash idiom to Zsh or Fish without
checking the shell-specific reference first.
**Error-handling stance**: flag `set -e`/`set -u` (or Zsh's
`ERR_EXIT`/`NO_UNSET`) as an anti-pattern when present, not as something
to require when absent — keep `pipefail`. Full reasoning in
`references/bash-pitfalls.md`; don't contradict it.
## Reference files
Load only the file(s) relevant to the current script — don't read all of
them for a small Bash script:
| Topic | File | When to read |
|-------|------|--------------|
| Bash style/structure | `references/bash-style-guide.md` | Any Bash script — formatting, quoting, naming, `main` pattern, when shell is the wrong tool |
| ShellCheck codes | `references/shellcheck-codes.md` | Explaining/prioritizing ShellCheck findings for Bash/sh; also covers ShellCheck's blind spots |
| Bash pitfalls + error handling | `references/bash-pitfalls.md` | Runtime bugs ShellCheck under-explains, and this skill's explicit-checks-over-`set -e`/`-u` stance |
| Security | `references/security-checklist.md` | Every review, every dialect — read this one unconditionally |
| Fish | `references/fish-guide.md` | Any `.fish` file or fish shebang |
| Zsh | `references/zsh-guide.md` | Any `.zsh` file or zsh shebang |
## Step 1: Identify the dialect
Run the detector against the target file:
```bash
scripts/detect_shell.sh <file>
```
(Resolve the path relative to this skill's own directory — the script
inspects the shebang first, then extension, then sniffs for
dialect-specific syntax as a last resort.) If it reports `unknown` or
`sh`, and the ambiguity matters (e.g. the file mixes bashisms with a `sh`
shebang), ask the user which dialect they intend, or infer from context
(array usage, `function` keyword, `set`/`end` blocks) and state the
assumption in your output.
Route to the correct reference file(s) for that dialect before doing
anything else.
## Step 2: Run static analysis first when possible
- **Bash/sh**: run `scripts/run_shellcheck.sh <file> [bash|sh]` and
`scripts/run_shfmt_check.sh <file>`. Treat ShellCheck's output as ground
truth for the codes it covers — don't re-derive a rule ShellCheck
already flagged, explain and prioritize its actual findings instead
(cross-reference `references/shellcheck-codes.md` for the fix pattern).
- **Zsh**: run `scripts/run_shellcheck.sh <file> bash` as a best-effort
approximation for portable constructs only. Explicitly call out
Zsh-specific constructs it cannot validate (word-splitting differences,
1-based arrays, `setopt` behavior) and rely on
`references/zsh-guide.md` for those.
- **Fish**: ShellCheck does not apply. If `fish` is available, run
`fish -n <file>` for syntax-only validation. All substantive review is
manual, driven by `references/fish-guide.md`.
- If a tool isn't installed, the wrapper scripts report that plainly —
note it in your output as reduced coverage rather than silently skipping
the category.
## Step 3: Apply manual review categories, in this priority order
### a. Security (highest priority)
Read `references/security-checklist.md` unconditionally. Check for:
`eval` on untrusted input, unquoted expansions of external input,
predictable temp file paths (vs. `mktemp` + `trap EXIT`), credentials in
argv/env, missing input validation/allowlisting, unsafe `PATH`
assumptions, unnecessary root/SUID execution.
### b. Correctness / robustness
Unchecked exit statuses on critical operations — `cd`, destructive
`rm`/`mv`/`cp`, a build/deploy step — are always a finding, independent of
whether `set -e` is present (see the error-handling stance above and
`references/bash-pitfalls.md`). Also check: incorrect word-splitting
assumptions for the dialect in use; parsing `ls` output; TOCTOU race
conditions in check-then-act file operations. Fish has no errexit
equivalent at all — for `.fish` files check `$status`/`and`/`or` usage per
`references/fish-guide.md` instead.
### c. Portability
Shebang correctness vs. actual syntax used (e.g. bashisms under
`#!/bin/sh` — ShellCheck SC3045 and friends); shell-version-dependent
features; assumptions about GNU vs. BSD utility flags; Zsh scripts relying
on default word-splitting/glob behavior that would break under `sh`
emulation or Bash.
### d. Style / maintainability
Indentation consistency, quoting conventions, naming conventions,
function structure and the `main`/`main "$@"` pattern (Bash), documentation
completeness, line length, and script length — flag scripts near or over
~100 lines as candidates for a rewrite in a structured language, per the
Google Shell Style Guide's own guidance in `references/bash-style-guide.md`.
## Step 4: Output format
For each finding, report:
- **Location**: `file:line`
- **Severity**: Critical / High / Medium / Low
- **Category**: one of Security, Correctness, Portability, Style (from
Step 3)
- **Explanation**: one sentence on the actual risk in this script's
context, not a generic restatement of the rule
- **Fix**: a concrete before/after code snippet
Group findings by severity, security/critical issues first. End with a
short summary count table by severity and by category.
**Do not silently auto-fix.** Always show the proposed diff for user
approval, unless the user explicitly asked you to apply fixes directly
(e.g. via `--fix`) — and even then, summarize what changed after applying.
### Output skeleton
```markdown
## Shell Script Review: <file>
**Dialect**: bash | zsh | fish **Lines**: <n>
**Static analysis**: shellcheck (n findings) | shfmt (drift: yes/no) | not available
### Critical
#### 1. <title>
**Severity**: Critical | **Category**: Security
**Location**: `file:line`
**Risk**: <one sentence>
**Current**:
\`\`\`bash
...
\`\`\`
**Fix**:
\`\`\`bash
...
\`\`\`
### High
...
### Medium
...
### Low
...
### Summary
| Severity | Count |
|----------|-------|
| Critical | n |
| High | n |
| Medium | n |
| Low | n |
| Category | Count |
|----------|-------|
| Security | n |
| Correctness | n |
| Portability | n |
| Style | n |
```
## Step 5: Escalation rule
If ShellCheck and manual review disagree, or a construct's safety depends
on a runtime value ShellCheck can't see (dynamic `eval` targets, indirect
variable references, values crossing into an embedded `awk`/`sed`/SQL
snippet), **flag it as "needs runtime verification"** rather than
asserting certainty either way, and recommend a BATS test case that
exercises the risky path with adversarial input.
## Task execution
Based on `$ARGUMENTS`:
- **A file or directory is given**: review it (recurse for a directory,
one report per file plus a combined summary).
- **`--security` is given**: narrow the review to Step 3a only, but still
run static analysis first.
- **`--fix` is given**: after presenting findings and getting
confirmation, apply fixes in this order, then re-run static analysis to
confirm, then report a summary of what changed:
1. ShellCheck's own suggested fixes (Bash/sh only):
`scripts/run_shellcheck.sh <file> <dialect> diff | patch -p1`
2. Formatting: `shfmt -w -i 2 -ci -bn -sr -- <file>`
3. Hand-apply the remaining findings that neither tool can fix
(security issues, `-e`/`-u` removal plus the explicit checks that
replace them, anything flagged "needs runtime verification").
- **Script content is pasted with no file**: write it to a temp file
(`mktemp`, matching the dialect's extension) for the static-analysis
tools to run against, then review as normal; clean up the temp file
afterward.
- **Nothing specified**: review unstaged/staged shell script changes via
`git diff` (filter to `*.sh`, `*.bash`, `*.zsh`, `*.fish` paths).
Your goal is to **ground every finding in a named authority** (Google
Shell Style Guide, a specific ShellCheck code, BashPitfalls, or the
security checklist) so feedback is actionable and verifiable, not a matter
of taste — and to be explicit about the difference between "ShellCheck
confirmed this" and "this needs a human/runtime check" for the dialects
and constructs static analysis can't fully cover.
Files in this package (11)
- SKILL.md 9 KB
- evals.json 11 KB
- references/bash-pitfalls.md 7 KB
- references/bash-style-guide.md 7 KB
- references/fish-guide.md 7 KB
- references/security-checklist.md 5 KB
- references/shellcheck-codes.md 7 KB
- references/zsh-guide.md 6 KB
- scripts/detect_shell.sh 2 KB
- scripts/run_shellcheck.sh 1 KB
- scripts/run_shfmt_check.sh 1 KB
Versions
The database has no other skills named shell-script-reviewer.
Database snapshot: 13.11.2026 · package version 033457d833ae (SHA-256 digest of the entire package)
Downloads in the last 30 days: 1 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100shell-scripting
Bash, Zsh, POSIX sh, Fish scripts, one-liners, dotfiles, completions. Use for quoting or globbing bugs, shellcheck warnings, porting between shells. - 90shell-scripts
Use when writing or reviewing Bash scripts and shell snippets, especially for shebang selection, quoting, parameter expansion ("${VAR}" style), test expressions (`[ ]` vs `[[ ]]`), ShellCheck-guided fixes, and portability decisions across POSIX sh, Bash, and zsh compatibility targets. - 100shell
Shell scripting best practices and conventions for bash, sh, zsh, and other shells Triggers on: **/*.sh - 95glab-completion
Generate shell completion scripts for bash, zsh, fish, or PowerShell. Use when setting up glab autocompletion for your shell. Triggers on completion, autocomplete, shell completion, tab completion. - 100shellcheck
Shell script static analysis and linting. USE WHEN shellcheck, lint shell, bash lint, sh lint, script analysis, shell errors, SC codes, shell best practices. Comprehensive shell script validation with CI/CD integration. - 100review-shell-scripts
Review all shell scripts against the Bash Script Convention. Use when you need to check script compliance or before committing changes.