From shell-routines
Debug a failing bash script: reproduce the failure, isolate the cause with non-invasive tracing (bash -x, bash -n, ShellCheck), then apply and verify the fix. Use when a script errors at runtime, crashes, exits non-zero, or produces wrong output ("debug this script", "fix my script", "why is this failing"). For a script that works but runs slowly, use shell-profiling; for quality review of a working script, use shell-review.
How this skill is triggered — by the user, by Claude, or both
Slash command
/shell-routines:shell-debuggingThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Guides systematic debugging of bash scripts to identify and resolve issues efficiently.
Guides systematic debugging of bash scripts to identify and resolve issues efficiently.
Scope: This skill handles runtime failures — scripts that error, crash, or produce wrong output. For quality assessment of a working script, use shell-review instead.
Design principle: Never leave debug instrumentation in the target script. Use non-invasive methods (bash -x) first; when targeted tracing is needed, instrument a temporary copy and discard it afterwards.
Target script: $ARGUMENTS
If $ARGUMENTS is not provided, ask the user which script needs debugging.
Understand the failure:
$? after the failing command?Read $ARGUMENTS to understand:
Non-invasive — run with tracing from the command line, no file modification:
bash -x script.sh args
+ prefix indicates the command being executedTargeted tracing — when you need tracing around a specific section only, create a temporary copy:
cp script.sh /tmp/script.debug.sh
# Add set -x / set +x around the suspect section in the copy
bash /tmp/script.debug.sh args
rm /tmp/script.debug.sh
bash -n script.sh
Warning: source executes all top-level code in the script. Before sourcing a broken script, inspect it for side effects (file operations, network calls, deployments). Consider using a container or VM for untrusted scripts.
# Source the script to load functions
source script.sh
# Call functions individually with test data
your_function "test_input"
Consult references/debugging-guide.md for:
Make the minimal change that resolves the root cause, not the symptom.
bash -n is clean; no new errors introducedDone when the reported failure no longer reproduces under the original invocation, bash -n and ShellCheck are clean, and the script holds no leftover set -x or debug prints.
references/debugging-guide.md -- Error pattern tables, debugging checklist, common issue solutions, advanced techniques (custom PS4, timing, call logging), ShellCheck quick referenceAlways read all references and examples before producing output.
examples/debug-session.md -- Walks through diagnosing an unbound variable error from start to finishshell-best-practices -- Prevent issues before they occurshell-review -- Quality assessment once the script is workingshell-profiling -- For scripts that work correctly but run too slowly. See profiling workflow for timing, tracing, and benchmarking./shell-audit command -- Comprehensive quality checksnpx claudepluginhub objctp/shell-routinesBlocks Edit/Write/Bash actions until Claude investigates importers, data schemas, and user instructions. Improves output quality by forcing concrete facts before edits.