---
name: bash-auditor
description: Write, audit, and explain Bash scripts for DevOps use cases — deployments, monitoring, automation, and system administration — with strict safety and idempotency standards.
---

## Trigger Phrases
Use this skill when the request involves writing, reviewing, or explaining a Bash script, for example:

- "Write a Bash script to rotate log files older than 7 days."
- "Review this script for common Bash pitfalls."
- "Explain what this deployment script does."
- "Convert this into a safer script with proper error handling."
- "Write a health-check script that alerts via Slack webhook."
- "Why does this script silently fail sometimes?"

Do not use this skill for Python, Go, or other language scripts. Use for Bash and POSIX sh only.

## Deterministic Execution Flow

### Stage 0: Classify Request Mode

| Mode | User intent | Deliverable |
|------|-------------|-------------|
| `generate` | Write a new script from description | Complete script, production-safe |
| `audit` | Review an existing script for issues | Annotated issue list + corrected version |
| `explain` | Walk through what a script does | Section-by-section explanation |
| `convert` | Make an existing script safer/idempotent | Refactored script with change summary |

### Stage 1: Collect Inputs
For `generate` mode, ask for or assume:

| Input | Required | Safe default |
|-------|----------|-------------|
| What the script should do | Yes | — |
| Target OS / distro | Recommended | Ubuntu 22.04 LTS |
| Should it be idempotent? | Recommended | Yes |
| Error handling preference | Optional | `set -euo pipefail` |
| External dependencies (curl, jq, aws-cli, etc.) | Optional | State assumed dependencies |
| Sensitive values (tokens, passwords) | Optional | Always use environment variables, never hardcode |

For `audit` mode: paste the full script. No need for additional context unless the script has non-obvious dependencies.

### Stage 2: Safety Standards
Every generated or audited script must comply with these rules:

**Required header:**
```bash
#!/usr/bin/env bash
set -euo pipefail
IFS=$'\n\t'
```

**Variable safety:**
- All variables must be quoted: `"${VAR}"` not `$VAR`
- Arrays must use `"${array[@]}"` not `${array[*]}`
- Check for empty variables before using them in destructive operations

**Error handling:**
- Functions that can fail must check exit codes
- File operations must verify the file/path exists before acting on it
- External commands (curl, aws, kubectl) must have their exit codes handled

**Security:**
- Never hardcode credentials, tokens, or passwords
- Use environment variables for all secrets: `${SLACK_WEBHOOK_URL}` not a literal URL
- Log to stderr for errors: `echo "Error: ..." >&2`
- Avoid `eval` unless explicitly required and justified

**Idempotency:**
- File creation: check if file exists first
- Package installation: use `--no-install-recommends` and check if already installed
- Service restarts: check current state before restarting

### Stage 3: Audit Checklist
For `audit` mode, check each of the following and report findings:

| Category | Checks |
|----------|--------|
| Error handling | Missing `set -euo pipefail`, unhandled command exits |
| Variable quoting | Unquoted variables, especially in conditions and loops |
| Destructive operations | `rm -rf`, `dd`, `mkfs` without guard conditions |
| External dependencies | Commands called without checking availability (`command -v`) |
| Credentials | Hardcoded tokens, passwords, or API keys |
| Idempotency | Operations that fail or produce unintended results on re-run |
| Portability | Bash-specific syntax used where POSIX sh is expected |
| Silent failures | Pipes that swallow exit codes (`cmd1 | cmd2` without `pipefail`) |

Report findings as:
```
[CRITICAL] Line 14: Unquoted variable in rm command — can match unintended paths.
[WARNING]  Line 22: External command `jq` called without availability check.
[INFO]     Line 8: Using `yes/no` booleans — prefer `true/false` for clarity.
```

### Stage 4: Generate / Corrected Output
Present the corrected or generated script in a fenced code block, followed by:

```
## Summary
- [What the script does in 2 sentences]
- [Key safety features included]
- [Assumptions made]
- [Dependencies required: bash 4+, curl, jq, etc.]

## Usage
\`\`\`bash
[Exact command to run the script with required env vars]
\`\`\`
```

## Done Criteria
- Mode is classified (`generate`, `audit`, `explain`, `convert`).
- Generated output uses `set -euo pipefail` and proper quoting.
- No hardcoded credentials in generated or corrected scripts.
- Audit output lists findings by severity with line references.
- Usage section includes required environment variables.
- Idempotency is addressed for any script that modifies system state.