Agent skill

Shell

Shell scripting best practices for writing safe, portable, and maintainable bash/sh scripts.

MITAuto-check passedDevelopment

Install Shell

skills CLI

$ npx skills add pproenca/dot-skills --skill shell -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install pproenca/dot-skills shell --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/.experimental/shell .claude/skills/shell && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "shell" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/shell into .claude/skills/shell/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "shell", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/shell

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add pproenca/dot-skills --skill shell -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install pproenca/dot-skills shell --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/.experimental/shell .agents/skills/shell && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "shell" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/shell into .agents/skills/shell/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "shell", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add pproenca/dot-skills --skill shell -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install pproenca/dot-skills shell --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/.experimental/shell .cursor/skills/shell && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "shell" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/shell into .cursor/skills/shell/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "shell", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/pproenca/dot-skills.git --path skills/.experimental/shell

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add pproenca/dot-skills --skill shell -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install pproenca/dot-skills shell --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/.experimental/shell .gemini/skills/shell && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "shell" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/shell into .gemini/skills/shell/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "shell", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install pproenca/dot-skills shell

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add pproenca/dot-skills --skill shell -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/.experimental/shell .github/skills/shell && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "shell" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/shell into .github/skills/shell/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "shell", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add pproenca/dot-skills --skill shell -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install pproenca/dot-skills shell --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/.experimental/shell .opencode/skills/shell && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "shell" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/shell into .opencode/skills/shell/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "shell", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: shell
GitHub stars: 214
Token cost: ~1.9k tokens
SKILL.md length: 544 words
Files: 55 (incl. references, assets)
Skills in repo: 182
Repo updated: Aug 15, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Shell scripting best practices for writing safe, portable, and maintainable bash/sh scripts.

Works in 9 steps: Safety & Security (CRITICAL) → Portability (CRITICAL) → Error Handling (HIGH) → …
Refactoring shell scripts
SKILL.md covers When to Apply, Rule Categories by Priority, Quick Reference and How to Use, plus 2 more sections
Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Shell is an agent skill from pproenca/dot-skills. 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.

Its SKILL.md is about 1.9k tokens, which your agent loads only when the skill is triggered. The skill folder holds 57 other files, including reference files and assets (for example `AGENTS.md`, `README.md` and `assets/templates/_template.md`).

It sits in Development, covering Shell scripting, CI/CD and Containers. It works with Bash, Linux and Docker. The repository describes itself as: A collection of AI agent skills following the Agent Skills open format. The licence is MIT.

When your agent uses it

Refactoring shell scripts
Dockerfile RUN commands
Makefile recipes
CI pipeline scripts

Example prompts

“/shell”

Workflow steps

9 steps, taken from the step headings in SKILL.md.

Safety & Security (CRITICAL)
Portability (CRITICAL)
Error Handling (HIGH)
Variables & Data (HIGH)
Quoting & Expansion (MEDIUM-HIGH)
Functions & Structure (MEDIUM)
Testing & Conditionals (MEDIUM)
Performance (LOW-MEDIUM)
Style & Formatting (LOW)

What it can do on your machine

Read from SKILL.md and the folder at commit cf93c57. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md.
From the folder's file list and the shell code blocks in SKILL.md.
Network
Links to these hosts (documentation or services it may open):
- google.github.io
- shellcheck.net
- pubs.opengroup.org
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Shell loads about 1.9k tokens when it runs, and up to ~32k if it reads all its reference files. Until then it costs about 90 tokens; SKILL.md has 544 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~90
When it runs · the whole SKILL.md, loaded when a task matches: ~1.9k
With references · SKILL.md plus every file in references/, read only if the agent opens them: ~32k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from pproenca/dot-skills at commit cf93c57, republished under its MIT licence (© pproenca). 544 words, ~1,943 tokens.

Download SKILL.mdSave it as .claude/skills/shell/SKILL.md (or your agent's skills folder). This skill also uses 54 other files; get the full folder from GitHub.

name: shell
description: 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.

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 input
safety-eval-avoidance - Avoid eval for dynamic commands
safety-absolute-paths - Use absolute paths for external commands
safety-temp-files - Create secure temporary files
safety-suid-forbidden - Never use SUID/SGID on shell scripts
safety-argument-injection - Prevent argument injection with double dash

2. Portability (CRITICAL)

port-shebang-selection - Choose shebang based on portability needs
port-avoid-bashisms - Avoid bashisms in POSIX scripts
port-printf-over-echo - Use printf instead of echo for portability
port-export-syntax - Use portable export syntax
port-test-portability - Use portable test constructs

3. Error Handling (HIGH)

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

4. Variables & Data (HIGH)

var-use-arrays - Use arrays for lists instead of strings
var-local-scope - Use local for function variables
var-naming-conventions - Follow variable naming conventions
var-readonly-constants - Use readonly for constants
var-default-values - Use parameter expansion for defaults

Show full SKILL.md (218 more words)Show less

5. Quoting & Expansion (MEDIUM-HIGH)

quote-always-quote-variables - Always quote variable expansions
quote-dollar-at - Use "$@" for argument passing
quote-command-substitution - Quote command substitutions
quote-brace-expansion - Use braces for variable clarity
quote-here-documents - Use here documents for multi-line strings
quote-glob-safety - Control glob expansion explicitly

6. Functions & Structure (MEDIUM)

func-main-pattern - Use main() function pattern
func-single-purpose - Write single-purpose functions
func-return-values - Use return values correctly
func-documentation - Document functions with header comments
func-avoid-aliases - Prefer functions over aliases

7. Testing & Conditionals (MEDIUM)

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

8. Performance (LOW-MEDIUM)

perf-builtins-over-external - Use builtins over external commands
perf-avoid-subshells - Avoid unnecessary subshells
perf-process-substitution - Use process substitution for temp files
perf-read-files - Read files efficiently
perf-parameter-expansion - Use parameter expansion for string operations
perf-batch-operations - Batch operations instead of loops

9. Style & Formatting (LOW)

style-indentation - Use consistent indentation
style-file-structure - Follow consistent file structure
style-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

Files

SKILL.md and 54 other files (references, assets) in skills/.experimental/shell of pproenca/dot-skills.

SKILL.md
AGENTS.md
README.md
assets/templates/_template.md
metadata.json
references/_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
… and 37 more

Open the folder on GitHubat commit cf93c57

Compare with similar skills

Shell next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Shell compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Shell this skillpproenca/dot-skills	214	—	~1.9k	Automated safety check: Pass	MIT	1 mo ago
Headless Codex CLI AutomationXiaomiMiMo/MiMo-Code	14k	—	~2.7k	Automated safety check: Pass	MIT	4 days ago
GitHub Runnermagnus919/agent-skills	111	—	~1.7k	Automated safety check: Pass	MIT	yesterday
New Mac Setupswyxio/skills	172	—	~4.3k	Automated safety check: Pass	MIT	2 days ago
CI Adhoc Testnubjs/nub	4.4k	—	~1.7k	Automated safety check: Pass	MIT	today
Releasing MarchatCod-e-Codes/marchat	137	—	~801	Automated safety check: Pass	MIT	4 days ago

Similar skills

Headless Codex CLI Automation
XiaomiMiMo/MiMo-Code
Runs OpenAI Codex CLI as a non-interactive worker for CI, Docker, Kubernetes or remote servers, with sandbox modes and JSONL-friendly output.
14k GitHub stars~2.7k tokensUpdated 4 days ago
DevOps & CloudAuto-check passed
GitHub Runner
magnus919/agent-skills
Deploy, manage, and troubleshoot self-hosted GitHub Actions runners.
111 GitHub stars~1.7k tokensUpdated yesterday
DevOps & CloudAuto-check passed
New Mac Setup
swyxio/skills
Fully automated new Mac setup for fullstack web developers and AI engineers.
172 GitHub stars~4.3k tokensUpdated 2 days ago
DevOps & CloudAuto-check passed
CI Adhoc Test
nubjs/nub
Run ad-hoc / exploratory tests on a real OS or platform via CI when the behavior CANNOT be reproduced on the local host or in Docker — macOS Seatbelt / sandbox-exec / codesigning, Windows cmd.exe /…
4.4k GitHub stars~1.7k tokensUpdated today
DevOps & CloudAuto-check passed
Releasing Marchat
Cod-e-Codes/marchat
Prepares marchat releases: version bumps, CHANGELOG, packaging checksums, GitHub Actions release workflow, and Docker tags.
137 GitHub stars~801 tokensUpdated 4 days ago
DevOps & CloudAuto-check passed
Swig CI Repro
swig/swig
Reproduce a GitHub Actions Linux CI failure locally when it does not happen on your machine: a podman/docker image that mirrors the ubuntu-22.04 runner by reusing the real Tools/CI-linux-.sh install…
6.3k GitHub stars~1.2k tokensUpdated today
DevOps & CloudAuto-check passed

Questions about Shell

What does Shell do?

Shell scripting best practices for writing safe, portable, and maintainable bash/sh scripts. Shell is an agent skill from pproenca/dot-skills. Shell scripting best practices for writing safe, portable, and maintainable bash/sh scripts.

When should I use Shell?

Shell fits situations like: refactoring shell scripts; dockerfile RUN commands; makefile recipes; CI pipeline scripts.

How do I install Shell in Claude Code?

Run `npx skills add pproenca/dot-skills --skill shell -a claude-code`. Or copy the skill folder (skills/.experimental/shell in pproenca/dot-skills) into .claude/skills/shell in your project. Claude Code loads it when a task matches its description.

How do I install Shell in Codex?

Run `npx skills add pproenca/dot-skills --skill shell -a codex`. Or copy the skill folder (skills/.experimental/shell in pproenca/dot-skills) into .agents/skills/shell in your project. Codex loads it when a task matches its description.

Can I use Shell in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add pproenca/dot-skills --skill shell -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/shell, .gemini/skills/shell, .github/skills/shell and .opencode/skills/shell in your project.

What does Shell need to run?

SKILL.md names no scripts, command-line tools or credentials: Shell is instructions for the agent only.

Does Shell access the network?

SKILL.md names 3 domains. As links in the text: google.github.io, shellcheck.net and pubs.opengroup.org. This is read from the text; nothing was executed.

Is Shell safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Shell use?

Shell is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Shell use?

About 1.9k tokens (SKILL.md is roughly 7.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 30k tokens, read only when the agent opens those files.

What are the alternatives to Shell?

Skills that share tags, products or a category with Shell: Headless Codex CLI Automation (XiaomiMiMo/MiMo-Code, 14k stars), GitHub Runner (magnus919/agent-skills, 111 stars), New Mac Setup (swyxio/skills, 172 stars) and CI Adhoc Test (nubjs/nub, 4.4k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Shell?

pproenca (a GitHub user) maintains it in pproenca/dot-skills, which has 214 GitHub stars. The repository holds 182 skills in this directory. The repository was last updated on August 15, 2026.

Source: pproenca/dot-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Shell

Facts

At a glance

What it does

When your agent uses it

Example prompts

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Shell Scripts Best Practices (Community)

When to Apply

Rule Categories by Priority

Quick Reference

1. Safety & Security (CRITICAL)

2. Portability (CRITICAL)

3. Error Handling (HIGH)

4. Variables & Data (HIGH)

5. Quoting & Expansion (MEDIUM-HIGH)

6. Functions & Structure (MEDIUM)

7. Testing & Conditionals (MEDIUM)

8. Performance (LOW-MEDIUM)

9. Style & Formatting (LOW)

How to Use

Reference Files

Key Sources

Files

Compare with similar skills

Similar skills

More from pproenca/dot-skills

Related

Questions about Shell