Shell Skill Kit

Small, test-enforced shell rules for AI coding agents.

Bash, Zsh, POSIX sh, Nushell, shebangs, and streams, packaged as portable Agent Skills plus Claude Code and Codex metadata.

Skills | Install | Agent Surfaces | Quality Gates | Registry

---

What It Is

Shell Skill Kit is a lightweight rule pack for one risky place in AI coding: generated shell.

It is deliberately not a framework. The repo ships four things:

• short SKILL.md files that agents can load on demand;
• cited references for the reasoning behind each rule;
• runnable good/bad examples that CI checks;
• provider metadata for Codex, ChatGPT, Claude Code, Copilot, and other skill-aware tools.

The design contract is simple: tiny skill bodies, deep references, executable claims. If a shell rule cannot be cited or tested, it stays out.

Why It Exists

AI assistants often produce shell that works once and fails quietly later: unquoted expansions, wrong dialects, swallowed errors, stdout polluted with diagnostics, or Bash code hiding under #!/bin/sh.

Shell Skill Kit makes those failure modes harder to ship. *.good.sh examples must run and lint cleanly. *.bad.sh examples must trigger the exact ShellCheck codes they claim. Nushell examples must parse with nu --ide-check. When docs and reality drift, the build goes red.

Skills

Skill	Use it for
shell	The single entry point. Loads before you write any shell — picks the right tool first (often not shell), then applies the safety rules.

It routes into these on demand, so only what you need enters context:

Reference	Covers	Examples
cli-cheatsheets	how to check a tool (--help → man → context7), plus cached gotchas for fd/rg/sd/nu/jq/yq	prose
pipelines	replacing awk/sed/cut, BSD-vs-GNU sed -i, worked rewrites	prose
shell-standards	strict mode, quoting, arrays, traps, printf, [[ ]]	examples
bash	Bash error handling, arrays, macOS/BSD portability, bash-3.2 traps	examples
posix-sh	real /bin/sh, dash, no arrays, no bashisms	examples
zsh	zsh functions, options, globbing, no-fork performance	prose
nushell	structured pipelines, parse-time config, typed commands	examples
shebang	env, env -S, interpreter paths, dialect choice	examples
streams	stdin/stdout/stderr, redirection order, exit codes	examples

ShellCheck and shfmt do not support zsh, so zsh guidance is prose plus zsh -n syntax checking. For portable, lintable scripts, prefer Bash.

Install

Claude Code plugin:

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

Portable skill clients:

git clone https://github.com/posidoni/shell-skill
ln -s "$PWD/shell-skill/skills/shell" "$YOUR_SKILLS_DIR/shell"

Local development toolchain on macOS:

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

Linux CI installs pinned versions through tools/ci-install-linux.sh.

Agent Surfaces

Surface	Entry point
Codex / ChatGPT Cowork	.codex-plugin/plugin.json, .agents/skills/, .codex/config.toml, CHATGPT.md
Claude Code	CLAUDE.md, .claude-plugin/plugin.json, agents/shell-reviewer.md
GitHub Copilot	.github/copilot-instructions.md
Generic agents and crawlers	AGENTS.md, llms.txt, skills/*/SKILL.md

See REGISTRY.md for directory listings, ecosystem notes, and copy-ready submission text.

Quality Gates

task --list          # discover entrypoints
task ci             # core quality gate
task hooks          # lefthook pre-commit mirror across the repo
task ai-integrations # Codex, ChatGPT, plugin, and skill metadata

task ci runs formatting, shell linting, example checks, Nushell parsing, YAML schema-modeline checks, AI integration checks, and the bats suite.

Repository Map

Path	Purpose
skills/	portable Agent Skills
reference/	cited rule explanations
examples/	runnable good/bad contracts
tools/, tests/	verification scripts and bats tests
.agents/, .codex-plugin/, .claude-plugin/	AI provider packaging
schemas/	project-owned JSON Schemas
REGISTRY.md	listing drafts and discovery notes

Contributing

Read CONTRIBUTING.md for the example contract and PR checklist. Read AGENTS.md before agent-assisted edits. Security reports go through SECURITY.md.

License

MIT (c) 2026 Mikhail Kuznetsov (@posidoni)

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