shell
Shell scripting best practices for writing safe, portable, and maintainable bash/sh scripts. Use when 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, quoting, variables, set -euo pipefail.
- Installs
- 694
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/pproenca/dot-skills --skill shell- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads shell automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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- Prevent command injection from user inputsafety-eval-avoidance- Avoid eval for dynamic commandssafety-absolute-paths- Use absolute paths for external commandssafety-temp-files- Create secure temporary filessafety-suid-forbidden- Never use SUID/SGID on shell scriptssafety-argument-injection- Prevent argument injection with double dash
2. Portability (CRITICAL)
port-shebang-selection- Choose shebang based on portability needsport-avoid-bashisms- Avoid bashisms in POSIX scriptsport-printf-over-echo- Use printf instead of echo for portabilityport-export-syntax- Use portable export syntaxport-test-portability- Use portable test constructs
3. Error Handling (HIGH)
err-strict-mode- Use strict mode for error detectionerr-exit-codes- Use meaningful exit codeserr-trap-cleanup- Use trap for cleanup on exiterr-stderr-messages- Send error messages to stderrerr-pipefail- Use pipefail to catch pipeline errorserr-check-commands- Check command success explicitlyerr-shellcheck- Use ShellCheck for static analysiserr-debug-tracing- Use debug tracing with set -x and PS4
4. Variables & Data (HIGH)
var-use-arrays- Use arrays for lists instead of stringsvar-local-scope- Use local for function variablesvar-naming-conventions- Follow variable naming conventionsvar-readonly-constants- Use readonly for constantsvar-default-values- Use parameter expansion for defaults
5. Quoting & Expansion (MEDIUM-HIGH)
quote-always-quote-variables- Always quote variable expansionsquote-dollar-at- Use "$@" for argument passingquote-command-substitution- Quote command substitutionsquote-brace-expansion- Use braces for variable clarityquote-here-documents- Use here documents for multi-line stringsquote-glob-safety- Control glob expansion explicitly
6. Functions & Structure (MEDIUM)
func-main-pattern- Use main() function patternfunc-single-purpose- Write single-purpose functionsfunc-return-values- Use return values correctlyfunc-documentation- Document functions with header commentsfunc-avoid-aliases- Prefer functions over aliases
7. Testing & Conditionals (MEDIUM)
test-double-brackets- Use [[ ]] for tests in bashtest-arithmetic- Use (( )) for arithmetic comparisonstest-explicit-empty- Use explicit empty/non-empty string teststest-file-operators- Use correct file test operatorstest-case-patterns- Use case for pattern matching
8. Performance (LOW-MEDIUM)
perf-builtins-over-external- Use builtins over external commandsperf-avoid-subshells- Avoid unnecessary subshellsperf-process-substitution- Use process substitution for temp filesperf-read-files- Read files efficientlyperf-parameter-expansion- Use parameter expansion for string operationsperf-batch-operations- Batch operations instead of loops
9. Style & Formatting (LOW)
style-indentation- Use consistent indentationstyle-file-structure- Follow consistent file structurestyle-comments- Write useful comments
How to Use
Read individual reference files for detailed explanations and code examples:
- Section definitions - Category structure and impact levels
- Rule template - Template for adding new rules
Reference Files
| File | Description |
|---|---|
| AGENTS.md | Complete compiled guide with all rules |
| references/_sections.md | Category definitions and ordering |
| assets/templates/_template.md | Template for new rules |
| metadata.json | Version and reference information |
Key Sources
FAQ
What does the shell skill do?
Shell scripting best practices for writing safe, portable, and maintainable bash/sh scripts. Use when 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, quoting, variables, set -euo pipefail.
How do I install shell?
Run npx skills add https://github.com/pproenca/dot-skills --skill shell in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/shell/ (personal) or .claude/skills/shell/ (project).
Which AI agents can use shell?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is shell safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains shell?
It is published by pproenca in pproenca/dot-skills. It has 694 recorded installs.
More from pproenca/dot-skills
zod
pproenca/dot-skills
Zod schema validation best practices for type safety, parsing, and error handling. This skill should be used when defining z.object schemas, using z.string validations, safeParse, or z.infer. This skill does NOT cover React Hook Form integration patterns (use react-hook-form skill) or OpenAPI client generation (use orval skill).
vitest
pproenca/dot-skills
Vitest testing framework patterns for test setup, async testing, mocking with vi., snapshots, and test performance (formerly test-vitest). This skill should be used when writing or debugging Vitest tests. This skill does NOT cover TDD methodology (use test-tdd skill), API mocking with MSW (use test-msw skill), or Jest-specific APIs.
react-hook-form
pproenca/dot-skills
React Hook Form performance optimization for client-side form validation using useForm, useWatch, useController, useFieldArray, the subscribe() API, and the Watch / FormStateSubscribe / FieldArray render-prop components. Covers RHF 7.82 additions including resetDefaultValues() and the disabled field-array option. This skill should be used when building client-side controlled forms with React Hook Form library. This skill does NOT cover React 19 Server Actions, useActionState, or server-side form handling (use react-19 skill for those).
emilkowal-animations
pproenca/dot-skills
Emil Kowalski's animation best practices for web interfaces. Use when writing, reviewing, or implementing animations in React, CSS, or Framer Motion. Triggers on tasks involving transitions, easing, gestures, toasts, drawers, or motion.
nuqs
pproenca/dot-skills
nuqs (type-safe URL query state) best practices for Next.js and other React frameworks. This skill should be used when writing, reviewing, or refactoring code that uses nuqs for URL state management. Triggers on tasks involving useQueryState, useQueryStates, search params, URL state, query parameters, nuqs parsers, limitUrlUpdates, Standard Schema, NuqsAdapter, or Next.js routing with state.
clean-architecture
pproenca/dot-skills
Clean Architecture principles and best practices from Robert C. Martin's book. This skill should be used when designing software systems, reviewing code structure, or refactoring applications to achieve better separation of concerns. Triggers on tasks involving layers, boundaries, dependency direction, entities, use cases, or system architecture.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.