shellcheck — Claude Code skill: what it does, how to install
shellcheck runs static analysis on bash and sh scripts to catch quoting bugs, syntax errors, and POSIX mismatches while generating automated diff patches.
MIT 129 installs ★ 17 updated 2026-10-14
npx skills add julianobarbosa/claude-code-skills --skill shellcheck -a claude-codeWhat shellcheck does
The skill routes shell analysis through four distinct workflows: Analyze, Fix, Setup, and Explain. During execution, it sends event notifications to a local voice endpoint at http://localhost:8888/notify alongside standard terminal status messages.
It runs ShellCheck against bash and sh files to identify common pitfalls like unquoted variables (SC2086), unquoted command substitutions (SC2046), and scope issues. Dialect selection depends strictly on the script shebang. A script using #!/bin/sh will flag bashisms such as arrays or [[ ]] constructs.
Files loaded via source are ignored unless passed with the -x flag or marked by an inline source directive. If a script contains syntax parsing errors, running auto-fixes with the -f diff option will fail without generating patch files.
What it helps with
- detect unquoted variables and word-splitting bugs in shell scripts
- configure
.shellcheckrcand pre-commit hooks for a repository - explain ShellCheck warning codes like SC2086 with remediation examples
- generate and apply diff patches for detected script issues
Example prompts for the agent
- shellcheck my deploy script and group findings by severity
- fix the shellcheck errors in scripts/
- what does SC2086 mean and how do I resolve it?
How to install shellcheck
1Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill shellcheck -a claude-code2Manually: put the files in place
~/.claude/skills/shellcheck/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/shellcheck/
1Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill shellcheck -a codex2Manually: put the files in place
.agents/skills/shellcheck/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill shellcheck -a cursor2Manually: put the files in place
.cursor/skills/shellcheck/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install julianobarbosa/claude-code-skills skills/shellcheck2Manually: put the files in place
.github/skills/shellcheck/SKILL.md1Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill shellcheck -a gemini-cli2Platform CLI
gemini skills install https://github.com/julianobarbosa/claude-code-skills --path skills/shellcheckManually: put the files in place
.devin/skills/shellcheck/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add julianobarbosa/claude-code-skills --skill shellcheck -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about shellcheck
How do I install shellcheck in Claude Code?
Run npx skills add julianobarbosa/claude-code-skills --skill shellcheck -a claude-code. The skill file will be placed in ~/.claude/skills/shellcheck/SKILL.md.
What does the shellcheck skill do?
It connects your AI agent to ShellCheck workflows to inspect scripts, produce diff patches, explain SC rules, and create project linter configurations.
Why does ShellCheck ignore sourced files in scripts?
External files referenced via source are not followed by default. Full coverage requires adding the -x flag or including # shellcheck source=./lib.sh directives.
Source text
SKILL.md · MIT
---
name: shellcheck
description: 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.
---
# ShellCheck - Shell Script Static Analysis
**Auto-routes when user mentions shellcheck, shell linting, bash script analysis, or SC error codes.**
## Overview
ShellCheck is a GPLv3-licensed static analysis tool that identifies bugs in bash/sh shell scripts. It detects:
- Syntax errors and parsing issues
- Semantic problems causing unexpected behavior
- Quoting issues and word splitting bugs
- POSIX compatibility warnings
- Style and best practice violations
## Voice Notification
**When executing a workflow, do BOTH:**
1. **Send voice notification**:
```bash
curl -s -X POST http://localhost:8888/notify \
-H "Content-Type: application/json" \
-d '{"message": "Running the WORKFLOWNAME workflow from the ShellCheck skill"}' \
> /dev/null 2>&1 &
```
2. **Output text notification**:
```
Running the **WorkflowName** workflow from the **ShellCheck** skill...
```
## Workflow Routing
| Workflow | Trigger | File |
|----------|---------|------|
| **Analyze** | "shellcheck this", "lint script", "check shell" | `Workflows/Analyze.md` |
| **Fix** | "fix shell errors", "apply shellcheck fixes" | `Workflows/Fix.md` |
| **Setup** | "setup shellcheck", "configure shellcheck" | `Workflows/Setup.md` |
| **Explain** | "explain SC2086", "what is SC code" | `Workflows/Explain.md` |
## Quick Reference
### Basic Usage
```bash
# Check a script
shellcheck myscript.sh
# Specify shell dialect
shellcheck -s bash myscript.sh
# Exclude specific codes
shellcheck -e SC2086,SC2046 myscript.sh
# Output formats
shellcheck -f gcc myscript.sh # Editor integration
shellcheck -f json myscript.sh # Machine readable
shellcheck -f diff myscript.sh # Auto-fix patches
```
### Common SC Codes
| Code | Issue | Fix |
|------|-------|-----|
| SC2086 | Unquoted variable | `"$var"` |
| SC2046 | Unquoted command substitution | `"$(cmd)"` |
| SC2034 | Unused variable | Remove or export |
| SC2154 | Unassigned variable | Assign or disable |
| SC2155 | Declare and assign separately | Split declaration |
### Inline Directives
```bash
# Disable for next command
# shellcheck disable=SC2086
echo $var
# Disable for entire file (after shebang)
#!/bin/bash
# shellcheck disable=SC2086,SC2046
```
## Full Documentation
- Error Codes: `SkillSearch('shellcheck error codes')` -> loads ErrorCodes.md
- Configuration: `SkillSearch('shellcheck config')` -> loads Configuration.md
- CI/CD Integration: `SkillSearch('shellcheck ci')` -> loads Integration.md
- Best Practices: `SkillSearch('shellcheck practices')` -> loads BestPractices.md
## Examples
**Example 1: Analyze a script**
```
User: "shellcheck my deploy script"
-> Invokes Analyze workflow
-> Runs shellcheck with JSON output
-> Presents findings grouped by severity
-> Suggests fixes with wiki links
```
**Example 2: Fix common issues**
```
User: "fix the shellcheck errors in scripts/"
-> Invokes Fix workflow
-> Generates diff output
-> Applies fixes interactively
-> Re-runs validation
```
**Example 3: Setup for project**
```
User: "setup shellcheck for this repo"
-> Invokes Setup workflow
-> Creates .shellcheckrc
-> Adds pre-commit hook
-> Configures CI workflow
```
**Example 4: Explain an error code**
```
User: "what does SC2086 mean?"
-> Invokes Explain workflow
-> Fetches wiki documentation
-> Shows examples and fixes
-> Provides context-specific guidance
```
---
## Gotchas
- **SC2086 is wrong inside `[[ ]]`:** Bash's `[[ ]]` does not word-split, so `[[ -n $var ]]` is safe unquoted. Disabling SC2086 on `[[ ]]` blocks is a sign you're applying the lint to the wrong construct, not a sign the rule is broken.
- **SC2034 fires on indirectly-used variables:** Variables consumed via `${!prefix*}` indirection, `declare -p` introspection, or sourced into another script trigger "unused" false positives. Use `# shellcheck disable=SC2034` with a comment explaining the indirection — don't silence globally.
- **Shebang determines the dialect, not the filename:** `script.sh` with `#!/bin/sh` is checked as POSIX sh and rejects bashisms like `[[ ]]` or arrays. Either set the correct shebang or pass `-s bash` explicitly; never rely on the `.sh` extension.
- **`shellcheck -e SC2086,SC2046` in `.shellcheckrc` hides real bugs:** Project-wide disables compound — a year later nobody remembers why and unquoted expansions ship to prod. Prefer inline disables with a justification comment over global suppression.
- **Source-following requires `-x` flag:** `source ./lib.sh` is not analyzed by default. Run with `shellcheck -x script.sh` for full coverage, or add `# shellcheck source=./lib.sh` directives. CI configs frequently miss this and ship un-linted sourced files.
- **`-f diff` patches assume the script parses cleanly:** Syntax errors prevent the auto-fix output entirely, with no clear message. If `-f diff` produces nothing, run without `-f` first and fix parse errors before re-running for patches.
© julianobarbosa · MIT · julianobarbosa/claude-code-skills