| name | cli-scaffold-shell |
| description | This skill should be used when the user asks to "scaffold a Bash CLI", "generate a Zsh command-line tool", "create a PowerShell module CLI", "make a portable POSIX sh script", or names Bash, Zsh, PowerShell, or POSIX sh (sh/dash/ksh) as the target for a new command-line tool — either directly or dispatched from scaffold-cli's language-routing. Generates a freeform, production-grade CLI scaffold for the shell paradigm, following cli-architecture's five-pillar doctrine and this skill's own per-dialect reference idioms — never from stored boilerplate. |
Generate a production-grade CLI scaffold for one of the shell-paradigm
dialects — Bash, Zsh, PowerShell, or POSIX sh — freeform, every time,
guided by cli-architecture's doctrine and this skill's own per-dialect
reference file. Never copy a stored template; every file this skill
produces is written fresh from the pinned idioms below.
Step 1 — Load the doctrine
Invoke cli-architecture via the Skill tool if it has not already been
loaded this conversation (e.g. when this skill triggers directly by
natural language rather than via scaffold-cli's dispatch, which already
loads it). Every pillar in that doctrine applies to every dialect below —
this skill's reference files pin how, not whether.
Step 2 — Resolve the dialect and load its reference
| Requested dialect | Reference file |
|---|
| Bash | references/bash.md |
| Zsh | references/zsh.md |
| PowerShell, pwsh, ps1 | references/powershell.md |
| POSIX sh, sh, dash, ksh | references/posix-sh.md |
Read the resolved reference file in full before generating anything. Each
one is structured to map onto the five pillars: argument parsing,
project layout, help/completions, NO_COLOR-aware output, exit codes,
--json/--no-input, stdout/stderr discipline, distribution, snapshot
testing, and a minimal worked example (posix-sh.md additionally has a
dedicated "forbidden bashisms" section — see below).
Step 3 — Generate the scaffold
Follow the resolved reference's pinned idioms exactly:
- Argument parsing:
getopts for Bash, zparseopts for Zsh (Zsh's
own more ergonomic builtin — never substitute getopts for a Zsh
target), native [CmdletBinding()]/param() for PowerShell, POSIX
getopts only for POSIX sh.
- Core/backend separation: for Bash/Zsh/POSIX sh, generate a sourced
function file (
lib/<app>.sh, lib/<app>.zsh, or the POSIX-compliant
equivalent) with zero side effects at source-time, plus a thin bin/ <app> executable that sources it and dispatches. PowerShell is a
structural exception — always scaffold a formal module (<App>.psd1
manifest + <App>.psm1), never a standalone unwrapped .ps1 script;
the exported module functions ARE simultaneously the importable API
and the invokable CLI surface, so do not force an artificial thin-CLI
split that fights this ecosystem's own idiom — the reference's Core/
backend section states this explicitly, follow it as written.
- POSIX sh forbidden bashisms: when the resolved dialect is POSIX sh,
read
posix-sh.md's "Forbidden bashisms" section before writing a
single line and check every generated line against it — no arrays, no
[[ ]], no function keyword form, no == in [ ], no here-strings,
no process substitution. A single bashism silently breaks portability
to dash/BusyBox, which is the entire point of generating this dialect
instead of Bash — treat a violation here as a generation defect, not a
style nit.
- Exit codes: apply the frozen 0/1/2 contract from
cli-architecture.
None of the four shell dialects auto-emit this contract — getopts/
zparseopts set $? non-zero on parse failure but do not exit the
script themselves, and PowerShell's own parameter-validation failure
needs an explicit catch/remap too. Every dialect requires explicit
exit 2/exit(2) handling in the invalid-argument case — verify this
is present, never assume a framework default covers it here.
--json/--no-input, stdout/stderr, NO_COLOR: apply exactly as
each reference's corresponding sections specify — none of the four
dialects have automatic NO_COLOR support (PowerShell 7.2+'s $PSStyle
is the closest, and even that needs an explicit $env:NO_COLOR gate
per the reference) — hand-roll every one of these per the pinned idiom.- Distribution: generate the actual packaging metadata as part of the
scaffold — a Homebrew formula for Bash/Zsh/POSIX sh (with the honest
apt-optional note), and the PowerShell module manifest fields PSGallery
publishing requires.
- Snapshot testing: generate the
--help-snapshot test using each
reference's pinned tool (bats-core+golden-file for Bash/Zsh, shunit2+
golden-file for POSIX sh — note shunit2 specifically, never bats-core,
since bats itself requires bash and would defeat POSIX sh's whole
purpose — Pester+Compare-Object for PowerShell) as part of the
initial scaffold.
Use each reference's "Minimal worked example" section as a shape guide,
not literal text to copy — generated files should match the specific app
name and functionality the user described, freeform.
Step 4 — Verify before presenting
Hand the generated scaffold to the cli-scaffold-verifier agent (this
plugin's agents/cli-scaffold-verifier.md) for a read-only check against
cli-architecture's doctrine and this skill's resolved reference file —
for a POSIX sh target, this check must specifically include a bashism
sweep against posix-sh.md's forbidden-constructs list, not just the
general five-pillar check. Fix any reported gap and re-verify, except a
gap the verifier flags as needs-human-judgment, which should be
surfaced to the user directly instead of silently resolved either way.
Present
Report: which dialect and reference were used, the generated file tree,
and the verifier's summary (pass, or what was fixed, or what needs the
user's judgment — including any bashism sweep result for POSIX sh
targets). Note the distribution command the user would run to publish
it, and the test command to run the generated --help snapshot test.
