cli-audit-shell

Optimization: This skill uses on-demand loading. Heavy content lives in references/ and is loaded only when needed.

Language rule: Skill instructions are written in English. This skill targets Bash scripts exclusively. When generating user-facing output, detect the project's primary language (from README, comments, docs, commit messages) and produce the report in that language. If the project is bilingual, ask the user which language to use before proceeding.

Audit Shell — Shell Quality Index (SQI)

"Shell should only be used for small utilities or simple wrapper scripts." — Google Shell Style Guide

Core Principles

1. Evidence-based — every finding needs a file:line reference. No vague "the script could be better"
2. Proportional — a 500-line script doing LVM partitioning matters more than a 10-line wrapper. Scale to script complexity
3. Beyond shellcheck — shellcheck catches syntax; this skill catches semantic anti-patterns (dead code under set -e, redundant package checks, injections in heredocs)
4. Named anti-patterns — use the anti-pattern names from references/anti-patterns.md in findings
5. Positive reinforcement — always highlight good practices found
6. Complexity-adapted tooling — simple problems deserve simple tools (sed), complex problems deserve proper tools (kustomize). Read references/tooling-ladder.md
7. Gotchas — read ../gotchas.md before producing output to avoid known mistakes

Input

$ARGUMENTS is the target to audit (file path, directory, or empty for auto-detect).

• If a specific .sh file: audit that file deeply
• If a directory: audit all .sh files and shebanged scripts in it
• If empty: find all shell scripts in the project (glob **/*.sh + grep #!/bin/bash or #!/usr/bin/env bash)

12-Dimension Framework

Score each dimension 0.0-1.0, then compute a weighted SQI. Read references/categories.md for detailed checklists per category.

#	Category	Weight	Key question
S1	Strict Mode Coherence	12%	Is set -euo pipefail used AND is code compatible with it? No dead fallbacks?
S2	Error Surfaces & Return Values	12%	Are return values checked? No || true? No swallowed 2>/dev/null?
S3	Logging & Observability	8%	Uses logger(1) or structured output? Timestamps? Severity levels?
S4	Stderr Hygiene	5%	Errors to stderr, output to stdout? No blanket 2>/dev/null?
S5	Variable Discipline	10%	local in functions? No unquoted expansions? No injection in heredocs?
S6	Quoting & Expansion	8%	"${var}" not $var? Arrays for lists? "$@" not $*?
S7	Control Flow & Structure	8%	main() pattern? Functions near top? Early returns? Max depth 3?
S8	Naming Conventions	5%	lower_snake_case functions? UPPER_CASE constants? :: for packages?
S9	CLI Ergonomics	10%	getopts/getopt for options? --help? Single entry point vs N scripts? S9 follows the canonical surface mapping in ../shared/cli-ergonomics.md (Laws 1-3 applied to shell).
S10	Idempotency & Safety	10%	Check-before-create? No destructive assumptions? readonly for constants?
S11	Namespace & Env Hygiene	7%	Env vars prefixed by project? No global pollution? local everywhere?
S12	Security & Injection	5%	No eval? No unquoted user input in commands? No shell injection in env blocks?