shell-skill

A cited, test-enforced guide to writing safe, correct shell — Bash, Zsh, POSIX sh, and Nushell — for humans and AI coding agents.

Why · Skills · Quick start · Example contract · Use with agents · Contributing

---

The problem

AI coding assistants now write a large share of the world's shell — and a lot of it is quietly wrong: unquoted expansions, missing set -euo pipefail, [ ] where [[ ]] belongs, real errors swallowed by a stray || true. It works on the happy path and fails silently everywhere else. And the usual advice ("quote your variables") is folklore — unenforced, uncited, easy to skip.

shell-skill is the antidote. It encodes the rules as cited references, runnable examples that CI checks, and Agent Skills you can load into Claude, Codex, or Copilot — so the shell your tools (and you) produce is safe by default, not by luck.

Important

This repository enforces its own advice. *.good.sh examples must run to exit 0 and pass shellcheck + shfmt; *.bad.sh examples must trigger the exact ShellCheck codes they claim. If the docs drift from reality, CI goes red.

Why this exists

• Enforced, not asserted. The example contract is checked in CI, so the guidance cannot rot without breaking the build.
• Portable by default. Guidance calls out macOS Bash 3.2 and BSD-vs-GNU differences instead of assuming Linux + GNU coreutils — and CI runs the suite on both Linux and macOS, so that claim is checked, not just asserted.
• Judgment, not just syntax. It also covers when not to use shell — reach for Python or Go before a 300-line Bash script.
• Agent-ready. Ships AGENTS.md, CLAUDE.md, Copilot instructions, and an installable Claude Code plugin so the rules travel with your tools.

Skills

Skill	Covers	Reference	Examples
shell-standards	strict mode, quoting, [[ ]], arrays, traps, error handling	reference	examples
shebang	#!/usr/bin/env, env -S flags, absolute paths, dialect	reference	examples
streams	stdin/stdout/stderr, >&2, read -r, redirection order, here-docs	reference	examples
bash	error handling, macOS/BSD portability, arrays, temp files	reference	examples
posix-sh	no local, no arrays, [ ] not [[ ]], set -eu without pipefail	reference	examples
zsh	word-splitting, 1-indexed arrays, emulate, globbing	reference	prose
nushell	structured data, config load order, parse-time source	reference	examples

Note

ShellCheck and shfmt do not support zsh, so the zsh guidance is prose only — itself a reason to prefer Bash for portable, lintable scripts.

Quick start

Install the toolchain (macOS):

brew install shellcheck shfmt nushell bats-core go-task lefthook

Linux (pinned versions)

Use the versions CI installs — see tools/ci-install-linux.sh, which fetches pinned shfmt, nushell, and task binaries and installs shellcheck + bats from apt.

Then:

task            # list every entrypoint
task ci         # fmt-check, lint, examples, nushell, nushell-demo, test
task hooks      # run every git hook across the repo (lefthook)

This project uses Task, not Make — a single cross-platform binary with plain-YAML, self-documenting tasks. See CONTRIBUTING.md for the rationale.

The example contract

Examples live in examples/<domain>/ as paired files:

• NN-slug.good.sh — the correct pattern; self-contained, no arguments, exits 0, clean under shellcheck --severity=warning and shfmt.
• NN-slug.bad.sh — a safe-to-run anti-pattern carrying one directive: # expect-shellcheck: SC#### (codes ShellCheck must report) or # expect-shellcheck: none (a style-guide-only pitfall).

Nushell examples are *.nu, verified with nu --ide-check.

Use it with AI coding agents

Agent	Entry point
Codex, Cursor, general	AGENTS.md
Claude Code	CLAUDE.md, or install the plugin (below)
GitHub Copilot	.github/copilot-instructions.md

Install the Claude Code plugin:

/plugin marketplace add posidoni/shell-skill
/plugin install shell-skill@shell-skill

The plugin also ships a shell-reviewer subagent: it reviews Bash/POSIX sh/Zsh/Nushell changes strictly against this repo's own cited rules, running shellcheck/shfmt/nu --ide-check itself rather than eyeballing style.

Repository map

Path	What
skills/	Agent Skills (SKILL.md per domain)
reference/	in-depth references with citations
examples/	runnable good/bad pairs
tools/, tests/	verification scripts and the bats suite
.github/workflows/	CI (ShellCheck, shfmt, bats, Nushell, lefthook)
.claude-plugin/	plugin + marketplace manifests
Taskfile.yml	task runner entrypoints

Contributing

See CONTRIBUTING.md for the toolchain, the example contract, and the PR checklist. Please also read the Code of Conduct. Security reports: SECURITY.md. Curious how this was actually built — the research process, the enforcement discipline? See ENGINEERING.md.

References

The repository layout follows established Agent-Skills projects:

• anthropics/skills — the official Agent Skills repo; SKILL.md frontmatter and progressive disclosure.
• Agent Skills specification — the open standard.
• netresearch/skill-repo-skill — skill-repository layout, plugin packaging, and validation.

Related projects and curated indexes of Agent Skills: addyosmani/agent-skills, hesreallyhim/awesome-claude-code, travisvn/awesome-claude-skills, ComposioHQ/awesome-claude-skills, rohitg00/awesome-claude-code-toolkit, VoltAgent/awesome-claude-code-subagents.

Shell references and inspiration

The guidance draws on — and is indebted to — these sources:

• Google Shell Style Guide and the ShellCheck wiki — the backbone of the rules and codes.
• Greg's Wiki — BashFAQ & BashPitfalls — the definitive catalogue of shell gotchas.
• dylanaraps/pure-bash-bible — pure-bash alternatives to external commands.
• anordal/shellharden — a safety auto-corrector and its precise "what you don't need to quote" rules.
• koalaman/shellcheck — one page per diagnostic; the model for machine-checkable rules.
• romkatv/zsh-bench & Powerlevel10k — the zsh no-subprocess performance discipline.
• The Nushell Book — the Nushell chapters.
• Shebang mechanics: execve(2) and the merged Linux doc fix by @alurm.

License

MIT © 2026 Mikhail Kuznetsov (@posidoni)

---

_{Safe shell, for humans and the agents that write it.}