# Cli Audit Shell

> >

- **Type:** Skill
- **Install:** `agentstack add skill-destynova2-cli-code-skills-cli-audit-shell`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Destynova2](https://agentstack.voostack.com/s/destynova2)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Destynova2](https://github.com/Destynova2)
- **Source:** https://github.com/Destynova2/cli-code-skills/tree/main/cli-audit-shell

## Install

```sh
agentstack add skill-destynova2-cli-code-skills-cli-audit-shell
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

> **Optimization:** This skill uses on-demand loading. Heavy content lives in `references/` and is loaded only when needed.

> **Language rule:** Skill instructions are written in English. This skill targets Bash scripts exclusively. When generating user-facing output, detect the project's primary language (from README, comments, docs, commit messages) and produce the report in that language. If the project is bilingual, ask the user which language to use before proceeding.

# Audit Shell — Shell Quality Index (SQI)

> "Shell should only be used for small utilities or simple wrapper scripts." — Google Shell Style Guide

## Core Principles

1. **Evidence-based** — every finding needs a `file:line` reference. No vague "the script could be better"
2. **Proportional** — a 500-line script doing LVM partitioning matters more than a 10-line wrapper. Scale to script complexity
3. **Beyond shellcheck** — shellcheck catches syntax; this skill catches **semantic** anti-patterns (dead code under `set -e`, redundant package checks, injections in heredocs)
4. **Named anti-patterns** — use the anti-pattern names from `references/anti-patterns.md` in findings
5. **Positive reinforcement** — always highlight good practices found
6. **Complexity-adapted tooling** — simple problems deserve simple tools (sed), complex problems deserve proper tools (kustomize). Read `references/tooling-ladder.md`
7. **Gotchas** — read `../gotchas.md` before producing output to avoid known mistakes

## Input

`$ARGUMENTS` is the target to audit (file path, directory, or empty for auto-detect).

- If a specific `.sh` file: audit that file deeply
- If a directory: audit all `.sh` files and shebanged scripts in it
- If empty: find all shell scripts in the project (glob `**/*.sh` + grep `#!/bin/bash` or `#!/usr/bin/env bash`)

## 12-Dimension Framework

Score each dimension **0.0-1.0**, then compute a weighted SQI. Read `references/categories.md` for detailed checklists per category.

| # | Category | Weight | Key question |
|---|----------|--------|-------------|
| S1 | Strict Mode Coherence | 12% | Is `set -euo pipefail` used AND is code compatible with it? No dead fallbacks? |
| S2 | Error Surfaces & Return Values | 12% | Are return values checked? No `\|\| true`? No swallowed `2>/dev/null`? |
| S3 | Logging & Observability | 8% | Uses `logger(1)` or structured output? Timestamps? Severity levels? |
| S4 | Stderr Hygiene | 5% | Errors to stderr, output to stdout? No blanket `2>/dev/null`? |
| S5 | Variable Discipline | 10% | `local` in functions? No unquoted expansions? No injection in heredocs? |
| S6 | Quoting & Expansion | 8% | `"${var}"` not `$var`? Arrays for lists? `"$@"` not `$*`? |
| S7 | Control Flow & Structure | 8% | `main()` pattern? Functions near top? Early returns? Max depth 3? |
| S8 | Naming Conventions | 5% | `lower_snake_case` functions? `UPPER_CASE` constants? `::` for packages? |
| S9 | CLI Ergonomics | 10% | `getopts`/`getopt` for options? `--help`? Single entry point vs N scripts? S9 follows the canonical surface mapping in `../shared/cli-ergonomics.md` (Laws 1-3 applied to shell). |
| S10 | Idempotency & Safety | 10% | Check-before-create? No destructive assumptions? `readonly` for constants? |
| S11 | Namespace & Env Hygiene | 7% | Env vars prefixed by project? No global pollution? `local` everywhere? |
| S12 | Security & Injection | 5% | No `eval`? No unquoted user input in commands? No shell injection in env blocks? |

## Workflow

### Step 1 — Discover, sample, and detect language

Glob for shell scripts: `**/*.sh`, `**/Makefile`, shebanged files. For broad audit, prioritize: entry points (`setup.sh`, `install.sh`, `deploy.sh`), longest scripts, most-changed scripts (git log).

**Detect output language**: `git log --oneline -10` + `head -20 README.md`. Report in the project's language (French commits → French report).

### Step 2 — Detect script context

Classify each script:
| Type | Characteristics | Adjusted expectations |
|------|----------------|----------------------|
| **Installer/bootstrap** | Runs as root, creates users/mounts | S10 (idempotency) weight ×1.5, S12 (security) weight ×1.5 |
| **Library** (sourced) | Has `.sh` extension, no shebang exec | S8 (naming) weight ×1.5, S9 (CLI) weight ×0 |
| **Wrapper/glue** | 
```

If shellcheck is not installed, note it and proceed with manual analysis. Shellcheck findings go into the report but **don't duplicate** them in the dimension scores — this skill adds what shellcheck cannot see.

### Step 4 — Score all 12 dimensions

Read `references/categories.md` for detailed checks. For each category: collect evidence, assign score 0.0-1.0, note specific `file:line` findings.

### Step 5 — Detect anti-patterns

Read `references/anti-patterns.md` for named anti-patterns with detection heuristics. These are the **semantic** patterns shellcheck cannot find.

### Step 6 — Assess tooling fit

Read `references/tooling-ladder.md` for the complexity-adapted tooling decision tree. Flag scripts that use sed/awk for YAML when they should use yq/kustomize. Flag scripts that use kustomize for a 3-variable substitution when sed would suffice.

### Step 7 — Compute SQI and generate report

Read `references/scoring.md` for the SQI formula, severity classification, and benchmarks.

```
SQI = Sigma(wi x si) / Sigma(wi) x 10
```

Finding tier and confidence semantics are canonical in `../shared/triage.md` (Tier 3/2/1 + GRADE + triangulation). S-dimension findings carry tier and confidence so `cli-cycle` can aggregate without re-parsing.

## Output Format

```markdown
# Shell Audit -- {project-name}

**Target**: [file/directory] | **Scripts found**: [N] | **Date**: [date]
**SQI Score**: X.X/10 -- {verdict}
**Shellcheck**: [N warnings, M errors] (or "not available")

## Scores by Category

| # | Category | Weight | Score | Weighted | Key findings |
|---|----------|--------|-------|----------|-------------|
| S1-S12 rows with 0.0-1.0 scores... |
| | **SQI** | **100%** | | **X.X/10** | |

## Anti-Patterns Detected
| # | Pattern | Severity | File:Line | Recommendation |

## Critical Violations (must fix)
### [Category]: [violation title]
- **File**: `path/to/file:123`
- **What**: [description]
- **Why**: [named principle it violates + Google Shell Style Guide reference]
- **Fix**: [concrete code suggestion]

## Flags (should fix)
[same format]

## Tooling Recommendations
| Current tool | Used for | Recommended | Why |
[complexity-adapted tooling analysis]

## Good Practices Found
[positive reinforcement]

## Recommended Next Steps
1. [highest-impact fix first]
2. [second]
3. [third]
```

## What this skill does NOT do

- **Does not replace shellcheck** — it complements it with semantic analysis shellcheck can't do
- **Does not fix scripts** — it reports. Use the findings to guide refactoring
- **Does not audit non-shell code** — YAML, Dockerfiles, Terraform go to `cli-forge-infra`
- **Does not audit test strategy** — use `cli-audit-test` for that
- **Does not audit code topology** — use `cli-audit-tangle` for call graph analysis

## Integration with other cli-* skills

| Skill | Relationship |
|-------|-------------|
| `cli-audit-code` | Scores code quality generically. cli-audit-shell goes **deep on bash semantics** |
| `cli-forge-infra` | Audits infra config and ops patterns. cli-audit-shell audits the **scripts themselves** |
| `cli-audit-tangle` | Detects structural coupling. cli-audit-shell detects **bash-specific** structural issues |
| `cli-forge-pipeline` | Optimizes CI/CD pipelines. cli-audit-shell audits **shell scripts used in CI** |
| `cli-cycle` | Should call cli-audit-shell as part of full project review when shell scripts exist; emit `.claude/cli-audit-shell.json` per `../shared/result-schema.md` for orchestrator aggregation |

## Dynamic Handoffs

| Condition detected | Recommend | Why |
|-------------------|-----------|-----|
| Sed on YAML/JSON (AP7 Sed Surgeon) | `/cli-forge-infra` | Tooling ladder assessment, kustomize/yq recommendation |
| Multiple scripts without getopts (AP8 Script Hydra) | `/cli-audit-wizard` | UX audit of the setup/init flow |
| Shell injection risk in env blocks (AP9) | `/cli-audit-code` on the consuming code | Verify the sourcing code validates inputs |
| Scripts are CI/CD entrypoints | `/cli-forge-pipeline` | Pipeline-level optimization |
| Script > 100 lines with god functions | `/cli-audit-tangle` | Topology analysis for split points |
| Entrypoints with wait-for/sleep/`nc -z` loops or `sed` on app config | `/cli-audit-hanoi` | Displacement audit: trace the hack to the missing app capability |

**Rule:** Recommend, don't auto-execute.

## Reference Sources

- Google — *Shell Style Guide* (primary authority)
- Wooledge — *BashGuide*, *BashFAQ*, *BashPitfalls*
- ShellCheck — SC1000-SC9999 rule database
- Kfir Lavi — *Defensive Bash Programming*
- Dylan Araps — *Pure Bash Bible*
- Greg Wooledge — *Bash Idioms* (O'Reilly)
- SixArm — *Unix Shell Script Tactics* (XDG compliance, NO_COLOR standard, portability catalog)
- clig.dev — *Command Line Interface Guidelines* (CLI ergonomics, --json, --dry-run)
- no-color.org — *NO_COLOR standard* (color output gating)
- POSIX.1-2024 — Shell Command Language specification

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Destynova2](https://github.com/Destynova2)
- **Source:** [Destynova2/cli-code-skills](https://github.com/Destynova2/cli-code-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-destynova2-cli-code-skills-cli-audit-shell
- Seller: https://agentstack.voostack.com/s/destynova2
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.