playbooks

home / skills / athola / claude-night-market / shell-review

shell-review skill

/plugins/pensive/skills/shell-review

This skill audits shell scripts for correctness, safety, and portability, helping you ship reliable CI, hooks, and wrappers.

npx playbooks add skill athola/claude-night-market --skill shell-review

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
3.0 KB
---
name: shell-review
description: Audit shell scripts for correctness, portability, and common pitfalls.
  Use when reviewing shell scripts, CI scripts, hook scripts, wrapper scripts. Do
  not use when creating new scripts - use attune:workflow-setup.
category: build
tags:
- shell
- bash
- posix
- scripting
- ci
- hooks
tools:
- Read
- Grep
- Bash
complexity: intermediate
estimated_tokens: 200
progressive_loading: true
dependencies:
- pensive:shared
- imbue:evidence-logging
modules:
- exit-codes
- portability
- safety-patterns
---
## Table of Contents

- [Quick Start](#quick-start)
- [When to Use](#when-to-use)
- [Required TodoWrite Items](#required-todowrite-items)
- [Workflow](#workflow)
- [Output Format](#output-format)

# Shell Script Review

Audit shell scripts for correctness, safety, and portability.

## Verification

After review, run `shellcheck <script>` to verify fixes address identified issues.

## Testing

Run `pytest plugins/pensive/tests/skills/test_shell_review.py -v` to validate review patterns.

## Quick Start

```bash
/shell-review path/to/script.sh
```

## When To Use

- CI/CD pipeline scripts
- Git hook scripts
- Wrapper scripts (run-*.sh)
- Build automation scripts
- Pre-commit hook implementations

## When NOT To Use

- Non-shell scripts (Python, JS, etc.)
- One-liner commands that don't need review

## Required TodoWrite Items

1. `shell-review:context-mapped`
2. `shell-review:exit-codes-checked`
3. `shell-review:portability-checked`
4. `shell-review:safety-patterns-verified`
5. `shell-review:evidence-logged`

## Workflow

### Step 1: Map Context (`shell-review:context-mapped`)

Identify shell scripts:
```bash
# Find shell scripts
find . -name "*.sh" -type f | head -20
# Check shebangs
grep -l "^#!/" scripts/ hooks/ 2>/dev/null | head -10
```

Document:
- Script purpose and trigger context
- Integration points (make, pre-commit, CI)
- Expected inputs and outputs

### Step 2: Exit Code Audit (`shell-review:exit-codes-checked`)

@include modules/exit-codes.md

### Step 3: Portability Check (`shell-review:portability-checked`)

@include modules/portability.md

### Step 4: Safety Patterns (`shell-review:safety-patterns-verified`)

@include modules/safety-patterns.md

### Step 5: Evidence Log (`shell-review:evidence-logged`)

Use `imbue:evidence-logging` to record findings with file:line references.

Summarize:
- Critical issues (failures masked, security risks)
- Major issues (portability, maintainability)
- Minor issues (style, documentation)

## Output Format

```markdown
## Summary
Shell script review findings

## Scripts Reviewed
- [list with line counts]

## Exit Code Issues
### [E1] Pipeline masks failure
- Location: script.sh:42
- Pattern: `cmd | grep` loses exit code
- Fix: Use pipefail or capture separately

## Portability Issues
[cross-platform concerns]

## Safety Issues
[unquoted variables, missing set flags]

## Recommendation
Approve / Approve with actions / Block
```

## Exit Criteria

- Exit code propagation verified
- Portability issues documented
- Safety patterns checked
- Evidence logged

Overview

This skill audits shell scripts for correctness, portability, and common safety pitfalls. It targets scripts used in CI, hooks, wrappers, and build automation to surface exit-code problems, portability constraints, and unsafe patterns. Reviews are evidence-driven with file:line references and clear remediation suggestions.

How this skill works

The skill scans provided scripts, maps their runtime context, and inspects control flow for proper exit-code propagation and failure handling. It checks portability (POSIX vs bashisms), enforces safety patterns (quoting, set -euo pipefail, input validation), and logs findings with concrete examples and locations. After review it recommends fixes and suggests running shellcheck and tests to verify changes.

When to use it

  • Review CI/CD pipeline scripts before deployment
  • Audit git hooks and pre-commit scripts
  • Check wrapper and run-* helper scripts
  • Validate build and release automation scripts
  • Review scripted install or bootstrap actions

Best practices

  • Map each script’s trigger, inputs, outputs, and integration points before changing code
  • Ensure exit codes propagate: prefer set -o pipefail or explicit checks around pipelines
  • Favor POSIX-compliant constructs for portability, document intentional bashisms
  • Apply safety flags (set -euo pipefail) and handle unset variables and failures explicitly
  • Quote variables and validate external inputs; avoid parsing ls/grep output for data

Example use cases

  • CI job that sometimes hides failures due to unhandled pipelines
  • Pre-commit hook that runs linters but doesn’t fail the commit on linter errors
  • Wrapper script calling platform tools with differing flags across Linux and macOS
  • Build script that uses bash-specific features but must run in sh on minimal containers
  • Release installer script that reads untrusted filenames and risks word-splitting or globbing

FAQ

Should I use this skill when writing a new script?

No. This skill is designed for auditing existing scripts. For creating new scripts, use a workflow setup tool that enforces patterns and templates from the start.

How do I verify fixes after review?

Run shellcheck against the script and validate behavior in CI or with unit/integration tests. Re-run the review checklist to ensure exit-code, portability, and safety items are met.