Skip to content
Skills Library
Programming · Review & audit

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 ↗
Licence
MPL-2.0
Last repository change
22.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
11
Scripts
3
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.

Licence

MPL-2.0, otwarta.

What to check before installing
  • 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

  1. Reference files
  2. Step 1: Identify the dialect
  3. Step 2: Run static analysis first when possible
  4. Step 3: Apply manual review categories, in this priority order
  5. Step 4: Output format
  6. Step 5: Escalation rule
  7. Task execution
Original SKILL.md headings · 208 lines, 1,213 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.