Command Prompt

Command Prompt: Shell Scripting and Configuration

Reference skill for writing commands, scripts, and configuration across Unix shells. Detects the target shell from context and routes to the appropriate reference.

Target versions (September 2026):

• Zsh: 5.10
• Bash: 5.3
• Fish: 4.9.0
• Nushell: 0.115.1
• Tcsh: 6.24
• Dash: 0.5.13

When to use

• Writing shell commands, scripts, or one-liners
• Configuring dotfiles (.zshrc, .bashrc, .profile, config.fish)
• Writing completions, shell functions, or aliases
• Porting scripts between shells
• Debugging shell-specific behavior (globbing, arrays, expansion, quoting)
• Setting up oh-my-zsh, starship, p10k, or other shell frameworks
• Choosing which shell to target for a new script
• Writing interactive commands on the user's local machine (zsh)

When NOT to use

• Remote FreeBSD/OPNsense/pfSense commands - use firewall-appliance (handles tcsh/csh in the BSD context)
• Ansible shell/command modules - use ansible (module gotchas differ from raw shell)
• CI/CD pipeline shell blocks - use ci-cd (restricted environments, no interactive features)
• General Linux sysadmin that isn't shell-specific - just do the task directly

AI Self-Check

Before returning any generated shell script or command, verify:

• Shebang matches the detected target shell (not assumed bash)
• set -euo pipefail (bash/zsh) or set -eu (POSIX sh) present in scripts
• All variables double-quoted ("$var") unless word splitting is intentional
• No shell-isms from the wrong shell (no [[ ]] in #!/bin/sh, no BASH_SOURCE in zsh)
• Array indexing correct for the target shell (bash: 0-indexed, zsh: 1-indexed)
• printf used over echo for non-trivial output
• Glob safety guards in place (empty-glob case handled)
• No hardcoded paths for tools (/usr/bin/git) - use command -v or bare command names
• Temp files use mktemp with cleanup traps, not hardcoded /tmp/foo
• No secrets in command history (use read -s or environment variables)
• Shell identified: examples match POSIX sh, Bash, Zsh, or Fish semantics intentionally
• Quoting tested: paths with spaces, empty variables, and glob characters behave safely
• Cross-cutting agent hygiene applied - see references/agent-hygiene.md

Performance

• Use builtins and stream processing for large inputs; avoid command substitution that buffers entire files.
• Prefer rg, fd, and targeted file lists when available, with portable fallbacks noted.
• Avoid spawning subshells inside tight loops when xargs, arrays, or shell builtins fit.

Best Practices

• Default to set -euo pipefail only when the script is written to handle those semantics.
• Use -- before user-controlled paths for commands that support it.
• Preview destructive expansions before rm, mv, chmod, chown, or recursive edits.

Workflow

Step 1: Detect the target shell

Before writing any shell code, determine the target shell. Check these signals in order:

Task-based routing

Step 2: Load the right reference

Don't load all references. Pick the one that matches. If porting between two shells, load both.

Step 3: Write code, then verify

Use the cross-shell comparison below for quick lookups. After writing, run through the Verification Checklist at the bottom of this section.

Quick Cross-Shell Comparison

Universal Patterns (All POSIX Shells)

These work in sh, bash, and zsh. Fish has different syntax for most of these - see the alt-shells reference.

Piping and redirection

Chaining

Job control

Signals and traps

# Cleanup on exit (works in sh, bash, zsh)
cleanup() {
    rm -f "$tmpfile"
}
trap cleanup EXIT INT TERM

# Ignore a signal
trap '' HUP

# Common signals: EXIT (0), HUP (1), INT (2), TERM (15), USR1 (10), USR2 (12)

# Graceful kill with SIGTERM -> wait -> SIGKILL escalation
kill_gracefully() {
    local pid=$1 timeout=${2:-5}
    kill -TERM "$pid" 2>/dev/null || return
    local i=0
    while kill -0 "$pid" 2>/dev/null && [ $i -lt $timeout ]; do
        sleep 1; i=$((i+1))
    done
    kill -0 "$pid" 2>/dev/null && kill -KILL "$pid"
}

Interactive "kill by name" (zsh) - covers search, space-safe names, confirm, TERM->KILL escalation:

pk() {                                           # usage: pk <pattern>
    local pattern=$1 pids
    pids=(${(f)"$(pgrep -af -- "$pattern")"})    # -f matches full cmdline (spaces ok)
    (( $#pids )) || { print -u2 "no match"; return 1 }
    printf '%s\n' "${pids[@]}"                   # show PID + cmdline
    read -q "?kill these? [y/N] " || { print; return 1 }
    print
    for line in $pids; do kill_gracefully ${line%% *} 3; done
}

Quoting rules

Golden rule: when in doubt, double-quote. "$var" is almost always correct. Unquoted $var causes word splitting (in sh/bash) or glob expansion.

Exit codes

Common portable idioms

# Check if command exists
command -v git >/dev/null 2>&1 || { echo "git required" >&2; exit 1; }

# Default variable value
: "${VAR:=default}"       # set VAR to "default" if unset or empty
name="${1:-anonymous}"     # parameter default

# Temporary file (portable)
tmpfile=$(mktemp) || exit 1
trap 'rm -f "$tmpfile"' EXIT

# Read file line by line
while IFS= read -r line; do
    printf '%s\n' "$line"
done < file.txt

# Loop over glob results
for f in *.txt; do
    [ -e "$f" ] || continue    # guard against no matches (POSIX sh)
    echo "$f"
done

Completions Quick Reference (Zsh)

Zsh's completion system (compsys) handles subcommand routing natively. Minimal working example for a CLI tool with subcommands:

#compdef mycli

_mycli() {
  local -a subcmds=(
    'init:Initialize a new project'
    'build:Build the project'
    'deploy:Deploy to target environment'
  )

  _arguments -C \
    '(-h --help)'{-h,--help}'[Show help]' \
    '1:command:->subcmd' \
    '*::arg:->args'

  case $state in
    subcmd) _describe 'command' subcmds ;;
    args)
      case $words[1] in
        deploy) _arguments '--env[Target environment]:env:(dev staging prod)' ;;
      esac
      ;;
  esac
}

Place in a file named _mycli on your fpath, then ensure the directory is registered:

# In .zshrc, BEFORE compinit:
fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit

Or source inline with compdef _mycli mycli (no fpath needed). The reference files have deeper coverage: glob-qualified completions, _files, _hosts, _values, and async completion patterns.

Verification Checklist

Before returning any shell script, check:

• Shebang matches the target shell. #!/usr/bin/env bash for bash, #!/usr/bin/env zsh for zsh, #!/bin/sh for POSIX sh. Never #!/bin/bash (not portable across distros).
• set -euo pipefail present for bash and zsh scripts. For POSIX sh: set -eu (no pipefail).
• Variables are quoted. "$var" not $var, unless word splitting is intentional.
• No shell-isms in the wrong shell. No [[ ]] in #!/bin/sh. No BASH_SOURCE in zsh. No bash arrays in POSIX sh.
• Glob safety. POSIX sh: guard with [ -e "$f" ] || continue. Zsh: use (N) qualifier. Bash: shopt -s nullglob or guard.
• Array indexing matches the shell. Bash: 0-indexed. Zsh: 1-indexed. POSIX sh: no arrays.
• printf over echo for anything non-trivial (echo behavior varies across shells and platforms).

Reference Files

• references/zsh.md - Zsh 5.9/5.10 patterns, glob qualifiers, arrays, parameter expansion, completions, autoloading, dotfile config, prompt hooks, zsh-only features, 5.10 additions (non-forking ${ }, namerefs, SRANDOM), bash porting matrix
• references/bash.md - Bash 5.3 patterns, parameter expansion, arrays, conditionals, process substitution, error handling, traps, heredocs, coprocesses, bash 5.x features (non-forking ${ cmd; }, GLOBSORT, SRANDOM), script template
• references/posix-sh.md - Portable POSIX sh patterns, what's POSIX and what's not, bashism avoidance checklist, which-sh-am-I, arithmetic, parameter expansion, portable conditionals
• references/alt-shells.md - Fish 4.8 (syntax, functions, completions, config), tcsh/csh 6.24 (syntax, when you'll encounter it), Nushell 0.114 (structured pipelines, types), Elvish/Oils (brief)
• references/ssh-tmux-autostart.md - safe shell startup pattern for interactive SSH sessions that attach to tmux without breaking non-interactive commands

Output Contract

See references/output-contract.md for the full contract.

• Skill name: COMMAND-PROMPT
• Deliverable bucket: audits
• Mode: conditional. When invoked to analyze, review, audit, or improve existing repo content, emit the full contract - monospace inline header, severity-grouped inline summary, linked Markdown deliverable, and concise monospace conclusion - and write the deliverable to docs/local/audits/command-prompt/<YYYY-MM-DD>-<slug>.md. When invoked to write a script, dotfile, or completion / answer a question / teach a concept, respond freely: deliver the artifact or explanation inline without the contract, deliverable file, or conclusion table.
• Severity scale: P0 | P1 | P2 | P3 | info (see shared contract; only used in audit/review mode).

Related Skills

• firewall-appliance - OPNsense/pfSense uses tcsh/csh on FreeBSD. That skill handles the BSD firewall context; this skill covers tcsh syntax in general.
• ansible - Ansible shell/command modules have their own idiosyncrasies beyond raw shell scripting. Use ansible for playbook work.
• ci-cd - CI shell blocks run in restricted environments (no interactive features, possibly no bash). Use ci-cd for pipeline design; use this skill for the shell syntax within them.
• networking - Linux network configuration (interfaces, routes, firewalls, DNS). Use networking for service and protocol administration; use this skill for the shell scripts that wrap or automate those tasks.
• debian-ubuntu - Debian/Ubuntu system administration (packages, services, cloud-init). Use debian-ubuntu for distro-level operations; use this skill for the shell scripting patterns within those tasks.
• rhel-fedora - RHEL/Fedora system administration (dnf, systemd, SELinux, subscription-manager). Use rhel-fedora for distro-level operations; use this skill for the shell scripting patterns within those tasks.

Rules

1. Detect the shell first. Check shebang, file extension, or ask. Don't assume bash when the user might mean zsh.
2. Load the right reference. Don't wing zsh arrays or bash parameter expansion from memory - the subtle differences justify loading the reference every time.
3. Shebang is #!/usr/bin/env <shell>. Not #!/bin/bash. The env form is portable across distros. Exception: #!/bin/sh for POSIX scripts (this IS the standard form).
4. set -euo pipefail in every bash/zsh script. No exceptions for scripts beyond a one-liner.
5. User's interactive shell is zsh. When writing commands for the user to run locally, use zsh syntax. Bash for scripts and remote machines unless the script specifically needs zsh.
6. Don't mix shell syntaxes. A bash script uses bash idioms. A zsh script uses zsh idioms. "Works in both" compromises use neither well and confuse readers.
7. Quote your variables. "$var" is the default. Unquoted $var is the exception that needs justification.