| 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.
