shell

Files (55)

• AGENTS.md
• README.md
• SKILL.md
• _template.md · assets/templates/
• metadata.json
• _sections.md · references/
• err-check-commands.md · references/
• err-debug-tracing.md · references/
• err-exit-codes.md · references/
• err-pipefail.md · references/
• err-shellcheck.md · references/
• err-stderr-messages.md · references/
• err-strict-mode.md · references/
• err-trap-cleanup.md · references/
• func-avoid-aliases.md · references/
• func-documentation.md · references/
• func-main-pattern.md · references/
• func-return-values.md · references/
• func-single-purpose.md · references/
• perf-avoid-subshells.md · references/
• perf-batch-operations.md · references/
• perf-builtins-over-external.md · references/
• perf-parameter-expansion.md · references/
• perf-process-substitution.md · references/
• perf-read-files.md · references/
• port-avoid-bashisms.md · references/
• port-export-syntax.md · references/
• port-printf-over-echo.md · references/
• port-shebang-selection.md · references/
• port-test-portability.md · references/
• quote-always-quote-variables.md · references/
• quote-brace-expansion.md · references/
• quote-command-substitution.md · references/
• quote-dollar-at.md · references/
• quote-glob-safety.md · references/
• quote-here-documents.md · references/
• safety-absolute-paths.md · references/
• safety-argument-injection.md · references/
• safety-command-injection.md · references/
• safety-eval-avoidance.md · references/
• safety-suid-forbidden.md · references/
• safety-temp-files.md · references/
• style-comments.md · references/
• style-file-structure.md · references/
• style-indentation.md · references/
• test-arithmetic.md · references/
• test-case-patterns.md · references/
• test-double-brackets.md · references/
• test-explicit-empty.md · references/
• test-file-operators.md · references/
• var-default-values.md · references/
• var-local-scope.md · references/
• var-naming-conventions.md · references/
• var-readonly-constants.md · references/
• var-use-arrays.md · references/

SKILL.md (first lines)

# Shell Scripts Best Practices (Community)

Comprehensive best practices guide for shell scripting, designed for AI agents and LLMs. Contains 49 rules across 9 categories, prioritized by impact from critical (safety, portability) to incremental (style). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics.

## When to Apply

Reference these guidelines when:
- Writing new bash or POSIX shell scripts
- Reviewing shell scripts for security vulnerabilities
- Debugging scripts that fail silently or behave unexpectedly
- Porting scripts between Linux, macOS, and containers
- Optimizing shell script performance
- Setting up CI/CD pipelines with shell scripts

## Rule Categories by Priority

| Priority | Category | Impact | Prefix | Rules |
|----------|----------|--------|--------|-------|
| 1 | Safety & Security | CRITICAL | `safety-` | 6 |
| 2 | Portability | CRITICAL | `port-` | 5 |
| 3 | Error Handling | HIGH | `err-` | 8 |
| 4 | Variables & Data | HIGH | `var-` | 5 |
| 5 | Quoting & Expansion | MEDIUM-HIGH | `quote-` | 6 |
| 6 | Functions & Structure | MEDIUM | `func-` | 5 |
| 7 | Testing & Conditionals | MEDIUM | `test-` | 5 |
| 8 | Performance | LOW-MEDIUM | `perf-` | 6 |
| 9 | Style & Formatting | LOW | `style-` | 3 |

## Quick Reference

### 1. Safety & Security (CRITICAL)

- [`safety-command-injection`](references/safety-command-injection.md) - Prevent command injection from user input
- [`safety-eval-avoidance`](references/safety-eval-avoidance.md) - Avoid eval for dynamic commands
- [`safety-absolute-paths`](references/safety-absolute-paths.md) - Use absolute paths for external commands
- [`safety-temp-files`](references/safety-temp-files.md) - Create secure temporary files
- [`safety-suid-forbidden`](references/safety-suid-forbidden.md) - Never use SUID/SGID on shell scripts
- [`safety-argument-injection`](references/safety-argument-injection.md) - Prevent argument injection with double dash

### 2. Portability (CRITICAL)

- [`port-shebang-selection`](references/port-shebang-selection.md) - Choose shebang based on portability needs
- [`port-avoid-bashisms`](references/port-avoid-bashisms.md) - Avoid bashisms in POSIX scripts
- [`port-printf-over-echo`](references/port-printf-over-echo.md) - Use printf instead of echo for portability
- [`port-export-syntax`](references/port-export-syntax.md) - Use portable export syntax
- [`port-test-portability`](references/port-test-portability.md) - Use portable test constructs

### 3. Error Handling (HIGH)

- [`err-strict-mode`](references/err-strict-mode.md) - Use strict mode for error detection
- [`err-exit-codes`](references/err-exit-codes.md) - Use meaningful exit codes
- [`err-trap-cleanup`](references/err-trap-cleanup.md) - Use trap for cleanup on exit
- [`err-stderr-messages`](references/err-stderr-messages.md) - Send error messages to stderr
- [`err-pipefail`](references/err-pipefail.md) - Use pipefail to catch pipeline errors
- [`err-check-commands`](references/err-check-commands.md) - Check command success explicitly
- [`err-shellcheck`](references/err-shellcheck.md) - Use ShellCheck for static analysis
- [`err-debug-tracing`](references/err-debug-tracing.md) - Use debug tracing with set -x and PS4

### 4. Variables & Data (HIGH)

- [`var-use-arrays`](references/var-use-arrays.md) - Use arrays for lists instead of strings
- [`var-local-scope`](references/var-local-scope.md) - Use local for function variables
- [`var-naming-conventions`](references/var-naming-conventions.md) - Follow variable naming conventions
- [`var-readonly-constants`](references/var-readonly-constants.md) - Use readonly for constants
- [`var-default-values`](references/var-default-values.md) - Use parameter expansion for defaults

### 5. Quoting & Expansion (MEDIUM-HIGH)

- [`quote-always-quote-variables`](references/quote-always-quote-variables.md) - Always quote variable expansions
- [`quote-dollar-at`](references/quote-dollar-at.md) - Use "$@" for argument passing
- [`quote-command-substitution`](references/quote-command-substitution.md) - Quote command substitutions
- [`quote-brace-expansion`](references/quote-brace-expansion.md) - Use braces for variable clarity
- [`quote-here-documents`](references/quote-here-documents.md) - Use here documents for multi-line strings
- [`quote-glob-safety`](references/quote-glob-safety.md) - Control glob expansion explicitly

### 6. Functions & Structure (MEDIUM)

- [`func-main-pattern`](references/func-main-pattern.md) - Use main() function pattern
- [`func-single-purpose`](references/func-single-purpose.md) - Write single-purpose functions
- [`func-return-values`](references/func-return-values.md) - Use return values correctly
- [`func-documentation`](references/func-documentation.md) - Document functions with header comments
- [`func-avoid-aliases`](references/func-avoid-aliases.md) - Prefer functions over aliases

### 7. Testing & Conditionals (MEDIUM)

- [`test-double-brackets`](references/test-double-brackets.md) - Use [[ ]] for tests in bash
- [`test-arithmetic`](references/test-arithmetic.md) - Use (( )) for arithmetic comparisons
- [`test-explicit-empty`](references/test-explicit-empty.md) - Use explicit empty/non-empty string tests
- [`test-file-operators`](references/test-file-operators.md) - Use correct file test operators
- [`test-case-patterns`](references/test-case-patterns.md) - Use case for pattern matching

### 8. Performance (LOW-MEDIUM)

- [`perf-builtins-over-external`](references/perf-builtins-over-external.md) - Use builtins over external commands
- [`perf-avoid-subshells`](references/perf-avoid-subshells.md) - Avoid unnecessary subshells
- [`perf-process-substitution`](references/perf-process-substitution.md) - Use process substitution for temp files
- [`perf-read-files`](references/perf-read-files.md) - Read files efficiently
- [`perf-parameter-expansion`](references/perf-parameter-expansion.md) - Use parameter expansion for string operations
- [`perf-batch-operations`](references/perf-batch-operations.md) - Batch operations instead of loops

### 9. Style & Formatting (LOW)

- [`style-indentation`](references/style-indentation.md) - Use consistent indentation
- [`style-file-structure`](references/style-file-structure.md) - Follow consistent file structure
- [`style-comments`](references/style-comments.md) - Write useful comments


## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [AGENTS.md](AGENTS.md) | Complete compiled guide with all rules |

From pproenca/dot-skills, MIT.

More from pproenca/dot-skills