Menu
Best practices for writing tool and helper scripts. Use when creating bash scripts, automation tools, CLI utilities, or any executable that will be run repeatedly by humans or agents.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Dispatch Codex to review all unreviewed repository work, then verify its correlated findings ticket or clean result. Use when requesting an independent Codex review, auditing all changes, checking work since the last review, or waiting for Codex findings. Trigger: dispatch codex review, independent review, review all changes, check codex findings, run review agent.
Always-on: when a project has tickets, work the frontier (first unblocked open ticket), mark done, update plan status.
Incremental and full-history repository review with resumable adoption batches. Use when reviewing new work, initializing review tracking, reviewing all work to date, resuming historical review, inspecting unreviewed commits, or reviewing changed tickets. Trigger: review new work, adopt repository, review all history, resume review, review marker, unreviewed commits.
End-of-session handoff that captures current state for the next session. Use when ending a work session, switching context, or before a long break.
Consolidate project artifacts — promote scratch to memory, deduplicate memory, process decisions, organize scripts, update steering/skills accuracy. Use periodically or when the project feels cluttered.
Run and interpret crew-research evals — run.sh flags, scores.jsonl fields, activation TPR/FPR verdicts, resuming interrupted runs. Use when running evals, reading eval results, diagnosing a failing definition, or resuming a dead run. Trigger: run the evals, eval results, scores.jsonl, activation test, TPR, delta threshold, resume the run, skip-completed, known gap.
| name | script-authoring |
| description | Best practices for writing tool and helper scripts. Use when creating bash scripts, automation tools, CLI utilities, or any executable that will be run repeatedly by humans or agents. |
| metadata | {"type":"reference","invocation":"both","practice":null} |
Scripts are infrastructure. They run repeatedly, fail unexpectedly, and get inherited by people who didn't write them. Build for the second run, not the first.
Run twice, get the same result. Check state before acting.
# Bad: fails on second run
mkdir output/
# Good: safe to re-run
mkdir -p output/
Pattern: check-then-act. [[ -f "$file" ]] || create_it. Never assume clean state.
If interrupted, pick up where it left off. Use checkpoints for multi-step work.
# Checkpoint pattern
DONE_FILE=".state/${STEP}.done"
if [[ ! -f "$DONE_FILE" ]]; then
do_expensive_work
touch "$DONE_FILE"
fi
For long operations: write progress to a state file. On restart, read state and skip completed steps.
The user must always know: what's happening, how far along, and whether it's stuck.
echo "Step 2/5: Installing dependencies..."
# For loops:
echo " Processing $i/$total: $name"
Rules: announce each phase, show counts for loops, emit timing for slow operations.
set -euo pipefail # Always. No exceptions.
-e: exit on error-u: error on undefined variables-o pipefail: catch failures in pipesAdd trap cleanup EXIT for temp file cleanup on any exit path.
#!/bin/bash
# tools/my-script.sh — One-line description of what this does
# Usage: ./my-script.sh [--flag value] [--dry-run]
Every script starts with: shebang, description comment, usage comment. If it takes flags, show them.
| Pattern | Why |
|---|---|
set -euo pipefail | Fail fast, fail loud |
| Usage comment in header | Discoverable without reading code |
--dry-run flag for destructive scripts | Safe to test |
Temp dirs with trap cleanup | No orphaned files |
Absolute paths for key dirs (SCRIPT_DIR) | Works from any cwd |
| Exit codes: 0=success, 1=error, 2=usage | Composable with other tools |
cd then relative paths → compute absolute paths from SCRIPT_DIR|| true everywhere) → let errors propagate, handle specificallyPhase header (what's about to happen)
✅ Success detail
⚠️ Warning (non-fatal)
❌ Error (fatal)
---
Summary line (totals, timing)
Scripts must run on Windows (Git Bash), macOS, and Linux. Compatibility rules (sed/realpath/timeout portability, line endings, mise.toml patterns): references/cross-platform.md.