shell-scripts

name	shell-scripts
version	1.1
last_updated	2026-08-08
id	shell-scripts
one_line_purpose	Write and test shell scripts under system_files/.
entry_point	docs/skills/shell-scripts/SKILL.md
category	test-authoring
mcp_compliance_level	partial
optimization_status	draft
status	active
dependencies	[]
tags	["shell","bash","testing","bats","shellcheck"]
description	Shell script authoring and testability. Use when writing or testing shell scripts under system_files/, removing scripts, or adding bats tests.
metadata	{"type":"reference","context7-sources":["/koalaman/shellcheck","/bats-core/bats-core"]}

Shell Scripts — authoring and testability

Split from ci-tooling.md on 2026-06-24. This file holds shell script authoring patterns, testability idioms, and the mandatory touch-points when removing a script. ci-tooling.md retains CI policy and config; ci-pitfalls.md retains the incident log.

When to Use

• Writing or modifying a shell script under system_files/
• Writing bats tests for a shell script
• Debugging a shellcheck failure in validate.yml
• Removing a shell script from common (the 4 mandatory touch-points)

When NOT to Use

• CI workflow configuration (pre-commit, actionlint, SHA pinning) → ci-tooling.md
• CI incident log and silent failure patterns → ci-pitfalls.md

---

Removing a shell script from common — 4 mandatory touch-points

When deleting system_files/bluefin/usr/bin/<script>, check all four:

File	What to remove
.github/workflows/unit-tests.yml	The script path from the shellcheck run: block
.github/workflows/validate.yml	The shellcheck step that invokes it (if script-specific) and any candidates.append(Path("...")) entry in the Python OCI-ref guard
system_files/bluefin/usr/share/ublue-os/just/system.just	The just target and all aliases
docs/skills/	The script's skill file (if it has one) + its docs/SKILL.md routing row and any related skill links + all cross-references

Dead apt step hazard

If the validate.yml shellcheck step was the consumer of in that job, delete the apt install step too — it becomes a silent no-op that wastes ~20 seconds per CI run and confuses future readers.