Master ShellCheck static analysis configuration and usage for shell script quality. Use when setting up linting infrastructure, fixing code issues, or ensuring script portability.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Master ShellCheck static analysis configuration and usage for shell script quality. Use when setting up linting infrastructure, fixing code issues, or ensuring script portability.
Comprehensive guidance for configuring and using ShellCheck to improve shell script quality, catch common pitfalls, and enforce best practices through static code analysis.
Do not use this skill when
The task is unrelated to shellcheck configuration and static analysis
You need a different domain or tool outside this scope
Instructions
Clarify goals, constraints, and required inputs.
Apply relevant best practices and validate outcomes.
Provide actionable steps and verification.
If detailed examples are required, open resources/implementation-playbook.md.
Use this skill when
Setting up linting for shell scripts in CI/CD pipelines
Analyzing existing shell scripts for issues
Understanding ShellCheck error codes and warnings
Configuring ShellCheck for specific project requirements
Integrating ShellCheck into development workflows
Suppressing false positives and configuring rule sets
Enforcing consistent code quality standards
Migrating scripts to meet quality gates
ShellCheck Fundamentals
What is ShellCheck?
ShellCheck is a static analysis tool that analyzes shell scripts and detects problematic patterns. It supports:
Bash, sh, dash, ksh, and other POSIX shells
Over 100 different warnings and errors
Configuration for target shell and flags
Integration with editors and CI/CD systems
Installation
# macOS with Homebrew
brew install shellcheck
# Ubuntu/Debian
apt-get install shellcheck
# From source
git clone https://github.com/koalaman/shellcheck.git
cd shellcheck
make build
make install
# Verify installation
shellcheck --version
# SC1004: Backslash continuation not followed by newlineecho hello\
world # Error - needs line continuation# SC1008: Invalid data for operator `=='if [[ $var = "value" ]]; then# Space before ==truefi
SC2000-2099: Shell Issues
# SC2009: Consider using pgrep or pidof instead of grep|grep
ps aux | grep -v grep | grep myprocess # Use pgrep instead# SC2012: Use `ls` only for viewing. Use `find` for reliable outputfor file in $(ls -la) # Better: use find or globbing# SC2015: Avoid using && and || instead of if-then-else
[[ -f "$file" ]] && echo"found" || echo"not found"# Less clear# SC2016: Expressions don't expand in single quotesecho'$VAR'# Literal $VAR, not variable expansion# SC2026: This word is non-standard. Set POSIXLY_CORRECT# when using with scripts for other shells
SC2100-2199: Quoting Issues
# SC2086: Double quote to prevent globbing and word splittingfor i in$list; do# Should be: for i in $list or for i in "$list"echo"$i"done# SC2115: Literal tilde in path not expanded. Use $HOME instead
~/.bashrc # In strings, use "$HOME/.bashrc"# SC2181: Check exit code directly with `if`, not indirectly in a list
some_command
if [ $? -eq 0 ]; then# Better: if some_command; then# SC2206: Quote to prevent word splitting or set IFS
array=( $items ) # Should use: array=( $items )
SC3000-3999: POSIX Compliance Issues
# SC3010: In POSIX sh, use 'case' instead of 'cond && foo'
[[ $var == "value" ]] && do_something # Not POSIX# SC3043: In POSIX sh, use 'local' is undefinedfunctionmy_func() {
local var=value # Not POSIX in some shells
}
Practical Configuration Examples
Minimal Configuration (Strict POSIX)
#!/bin/bash# Configure for maximum portability
shellcheck \
--shell=sh \
--external-sources \
--check-sourced \
script.sh
Development Configuration (Bash with Relaxed Rules)
#!/bin/bash# Configure for Bash development
shellcheck \
--shell=bash \
--exclude=SC1091,SC2119 \
--enable=all \
script.sh
CI/CD Integration Configuration
#!/bin/bashset -Eeuo pipefail
# Analyze all shell scripts and fail on issues
find . -type f -name "*.sh" | whileread -r script; doecho"Checking: $script"
shellcheck \
--shell=bash \
--format=gcc \
--exclude=SC1091 \
"$script" || exit 1
done
.shellcheckrc for Project
# Shell dialect to analyze against
shell=bash
# Enable optional checks
enable=avoid-nullary-conditions,require-variable-braces,check-unassigned-uppercase
# Disable specific warnings
# SC1091: Not following sourced files (many false positives)
disable
