Shell
Apply 49 prioritized shell rules when writing or reviewing bash/sh in scripts, Dockerfiles, Makefiles, CI jobs, cron, and systemd units so failures are loud and portable.
Overview
shell is an agent skill most often used in Ship (also Build integrations, Operate infra) that enforces forty-nine prioritized bash/sh best-practice rules for safe, portable automation scripts.
Install
npx skills add https://github.com/pproenca/dot-skills --skill shellWhat is this skill?
- 49 shell scripting rules organized across 9 priority categories from safety to style
- Critical coverage for safety, portability, and error handling with incorrect vs correct examples
- Explicit triggers for Dockerfile RUN, Makefile recipes, CI pipelines, cron, and systemd ExecStart
- POSIX and bash guidance for Linux, macOS, and container targets including set -euo pipefail patterns
- Impact-tagged categories (CRITICAL through incremental) so agents fix highest-risk issues first
- 49 rules across 9 categories
- 6 safety-and-security rules in the highest-priority tier
Adoption & trust: 533 installs on skills.sh; 157 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your shell scripts fail quietly, break across OSes, or hide injection and quoting bugs in Docker and CI recipes.
Who is it for?
Indie devs who own Docker, Makefile, and CI shell themselves and want agent reviews grounded in POSIX-safe habits.
Skip if: Pure application-code projects with no shell, or teams that already enforce ShellCheck plus a written style guide in CI with zero script churn.
When should I use this skill?
Writing, reviewing, or refactoring shell scripts, Dockerfile RUN commands, Makefile recipes, CI pipeline scripts, cron jobs, or systemd ExecStart directives; triggers on bash, sh, POSIX, ShellCheck, error handling, quoti
What do I get? / Deliverables
You get review-ready shell with explicit error handling, quoting, and portability patterns aligned to high-impact rule categories before scripts hit cron or production CI.
- Review feedback mapped to prioritized shell rule categories
- Refactored script snippets with safer quoting and error handling
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Ship review because the skill is framed for reviewing and hardening shell code before it ships in automation. Review is where ShellCheck-style safety, quoting, and error-handling rules prevent silent CI and cron failures.
Where it fits
Refactor a Dockerfile RUN chain so failures propagate and paths stay quoted across multi-stage builds.
PR-review a GitHub Actions bash step for unquoted variables and missing errexit before merge.
Harden a nightly cron backup script with strict mode and portable path handling on Linux and macOS.
How it compares
Use this procedural rule set during agent review instead of one-off chat reminders about quoting and set -e.
Common Questions / FAQ
Who is shell for?
Solo builders and small teams who write or maintain bash/sh in repos, containers, CI, cron, or systemd and want LLM-assisted reviews tied to concrete rules.
When should I use shell?
Use it in Ship when reviewing automation PRs, in Build when authoring Dockerfile RUN or Makefile targets, and in Operate when hardening cron or systemd ExecStart scripts—any time triggers mention bash, sh, POSIX, ShellCheck, or set -euo pipefail.
Is shell safe to install?
It is documentation-style guidance; still review the Security Audits panel on this page and treat any generated scripts as untrusted until you run ShellCheck and tests in your environment.
SKILL.md
READMESKILL.md - Shell
# 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 convention