home / skills / julianobarbosa / claude-code-skills / shellcheck-skill

shellcheck-skill skill

safe

This skill analyzes shell scripts with ShellCheck to identify bugs, quoting issues, and best-practice improvements for safer, POSIX-compliant scripts.

npx playbooks add skill julianobarbosa/claude-code-skills --skill shellcheck-skill

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

Files (10)

SKILL.md

3.5 KB

---
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
```

Overview

This skill provides ShellCheck-based static analysis and linting for shell scripts (bash/sh). It finds syntax errors, quoting and word-splitting issues, POSIX compatibility problems, and style/best-practice violations. It integrates with CI/CD and can run analysis, apply automatic fixes, and explain SC error codes on demand.

How this skill works

The skill runs ShellCheck on target scripts and returns structured results (JSON, diff, or human-readable) grouped by severity and file location. It can generate automatic fix patches, apply fixes interactively, create project configuration (.shellcheckrc), and add pre-commit/CI hooks. When a workflow runs, it emits both a text notification and a background voice/HTTP notification to the local notifier endpoint so other systems can react.

When to use it

You want to lint or validate bash/sh scripts before commit or deployment
You see runtime shell errors or unpredictable word-splitting behavior
You need to enforce POSIX or project-specific shell style rules
You want CI/CD checks for shell scripts in pipelines
You need quick explanations for ShellCheck (SC) error codes

Best practices

Run ShellCheck with JSON output for machine parsing and CI reporting
Specify the shell dialect (-s bash, dash, etc.) to reduce false positives
Keep a .shellcheckrc to manage exclusions and project-specific rules
Prefer quoting variables ("$var") and command substitutions ($(cmd)) to avoid SC2086/SC2046
Use the diff/output mode for automated fix patches and review before apply

Example use cases

Analyze changed scripts in a pull request and output JSON results to CI
Run an interactive Fix workflow that generates diffs and optionally applies fixes
Create repository setup: add .shellcheckrc, pre-commit hook, and CI workflow for linting
Explain a specific SC code like SC2086 with examples and suggested fixes
Exclude particular rules locally using inline directives or project config

FAQ

Can this skill automatically fix all ShellCheck warnings?

It generates diff-style patches for many issues and can apply common fixes interactively, but some fixes require manual review and context-specific judgment.

How do I integrate this into CI?

Use JSON or gcc formatter output in your CI job, add a .shellcheckrc to the repo, and install a step that fails the build on defined severities or new issues.