shell-conventions

Enforce safety, quoting, and portability conventions for Bash and POSIX sh scripts.

Updated Feb 7, 2026
One-click install
npx skills add https://github.com/jsamuelsen11/claude-config --skill shell-conventions
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: shell-conventions
Source: https://github.com/jsamuelsen11/claude-config/tree/main/plugins/ccfg-shell/skills/shell-conventions
Command: npx skills add https://github.com/jsamuelsen11/claude-config --skill shell-conventions

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This set of conventions provides a comprehensive, language-agnostic guide for writing safe, readable, and portable shell scripts that work across Bash and POSIX sh, reducing common errors and security risks in automation tasks.

Core Features & Use Cases

  • Safety-focused rules: enforce strict mode usage, consistent quoting, trap-based cleanup, safe defaults, and a main() pattern to prevent accidental execution when sourced.
  • Portability and style: harmonize Bash and POSIX sh practices, promote shellcheck-friendly code, and enforce shfmt formatting for consistent style across teams; applicable to CI checks, onboarding, and code reviews.
  • Real-world use: ideal for scripting across automation, deployment tasks, and maintenance where reliability and portability matter.

Quick Start

Audit your shell scripts against the conventions and incrementally adopt the main patterns in new projects for safer, more maintainable code.

Frequently Asked Questions about shell-conventions

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
What are the best shell scripting conventions for safe and portable Bash code?

Safe shell scripting conventions enforce strict mode usage, consistent quoting, trap-based cleanup, and a main() pattern to prevent accidental execution. These rules ensure reliability and portability across Bash and POSIX sh environments.

How do I enforce shell script formatting and linting rules in a CI pipeline?

You can enforce shell script formatting and linting in CI pipelines by applying conventions that satisfy shellcheck rules for safety and shfmt for consistent style. This ensures portable code passes automated checks.

Does this shell convention guide support both Bash and POSIX sh?

Yes, these shell conventions harmonize Bash and POSIX sh practices to ensure portability. They promote shellcheck-friendly code and enforce shfmt formatting for consistent style across teams.

How do I resolve the script directory reliably in a portable shell script?

To resolve the script directory reliably, these shell conventions enforce specific SCRIPT_DIR resolution patterns. This ensures your script correctly locates files relative to its own path across different execution environments.

What is the main() pattern in shell scripting and when should I use it?

The main() pattern in shell scripting encapsulates execution logic within a function, preventing accidental execution when the script is sourced. Use it in all new scripts to ensure safe sourcing.

Why do my shell scripts fail when sourced by other scripts?

Shell scripts fail when sourced because they lack a main() pattern and proper safety flags, causing accidental execution. Adopting trap-based cleanup and strict mode conventions prevents these errors.