workmanship_report with sections: verdict, findings, changes, verification, residual_risk.
Installer Workmanship
Use this skill to write or repair an install script so a stranger can run it on
their machine, run it again, and undo it — without losing config, getting a
surprise password prompt, or being forced to reboot. An installer is a guest in
someone's home directory; it behaves accordingly.
⚠️ Critical Constraints
Idempotent: re-running changes nothing the second time. Every action
checks state before acting. Why: users re-run installers to repair or
upgrade; a non-idempotent script duplicates lines, restacks PATH, or fails.
Additive: never clobber the user's existing config. Append, merge, or
write a new file — never overwrite one you did not create. Why: a single
cp config ~/.config/app/config can erase hours of someone's customization.
WRONG: cp ./gitconfig ~/.gitconfig
CORRECT: back up first (cp ~/.gitconfig ~/.gitconfig.bak-$(date +%s)),
then merge or write only the keys you own.
No surprise sudo or reboots. Detect when privilege is needed, explain
why, and ask — never wrap the whole script in sudo. Why: a script that
silently escalates or reboots is indistinguishable from malware to a wary user.
Preflight before any mutation. Check OS, shell, required tools, disk,
network, and write permissions up front; fail with a clear message before
touching anything. Why: a half-applied install is worse than a refused one.
Fail loud, leave clean. Use set -euo pipefail; on error the host is in a
known state (untouched or rolled back), never half-configured.
Why This Exists
Most install scripts are written for the author's machine on the happy path:
they assume bash, assume sudo, assume nothing already exists, and assume one OS.
The first time a real user re-runs one, or runs it on a slightly different
system, it duplicates config, clobbers a dotfile, hangs on a password prompt, or
dies halfway and leaves a mess with no way back. This skill is the forcing
function for the trustworthy installer: safe to re-run, safe on a config that
already exists, honest about privilege, and reversible.
Quick Start
Locate or create the installer (install.sh, setup.sh, bootstrap.sh).
Inventory what it touches: files written, PATH/RC edits, packages, services.
For each action, confirm it is guarded (state-checked) and additive.
Add a preflight block at the top and an uninstall counterpart.
Run the four-way check: fresh run, re-run, partial-failure, uninstall.
Run bash scripts/validate.sh and report the verdict.
The Five Properties of a Trustworthy Installer
1. Idempotent (safe to re-run)
Every mutating step is preceded by a check. The pattern is test, then act:
Avoid bashisms if the shebang is #!/bin/sh; quote every path (spaces, ~).
4. No surprise privilege or reboots
Run as the invoking user by default. When a step genuinely needs root, isolate
it, explain it, and let the user decline:
need_sudo() {
command -v sudo >/dev/null || { echo"This step needs root; re-run as root." >&2; return 1; }
echo"About to install system packages (requires sudo): $*"sudo"$@"
}
Never call reboot; if a change needs a restart or a new shell, print the
instruction and let the user choose when.
5. Recovery and uninstall
Ship the undo with the install. A clear uninstall.sh (or install.sh --uninstall) removes what you added — and only what you added — restoring
backups where they exist. Print where backups went so recovery is obvious. Use
atomic writes for generated files (write to a temp path, validate, then mv
into place) so an interrupted run never leaves a half-written file.
Preflight Checks
Run before any mutation; fail fast with a precise message:
OS / arch supported (uname -s, uname -m).
Required tools present (command -v git curl ...), or installable.
Write permission to every target dir ([ -w "$DEST" ]).
Disk space / network if the install needs a download or sizeable write.
Existing install detected → switch to upgrade/repair, do not duplicate.
Audit Flow (for an existing installer)
List every side effect: file write, RC edit, package, service, symlink,
download, permission change.
For each side effect, ask: is it guarded (idempotent)? Is it additive (backs
up / merges)? Rewrite any that are not.
Confirm a preflight block exists and covers OS, tools, and permissions.
Model at least three runs: fresh install, repeat install, and partial install
after an early failure. Each must leave a sane state.
Check privilege: is sudo scoped to the steps that need it, with an
explanation? Is there any silent reboot?
Confirm an uninstall/recovery path exists and reverses exactly the install;
confirm verification proves the thing works, not just that files exist.
Output Specification
Return a workmanship report (also applied to the installer when repairing):
Verdict: pass, needs work, or blocked.
Findings: ordered by severity, each tied to one of the five properties.
Changes: what was edited and why.
Verification: the commands run (fresh / re-run / uninstall) and results.
