notque/vexjoy-agent / skills/infrastructure/deploy
deploy
FlaggedDeploy and infrastructure: web deploy, cron, package install, shell configuration.
references/zsh-shell-config.md
View on GitHub
# Zsh Shell Configuration Skill
Zsh is POSIX-compatible with powerful extensions. Every pattern here targets Zsh 5.8+ (ships with macOS 14+, Ubuntu 22.04+). All generated code must use Zsh-native syntax — `typeset`/`local` for scoping, `path` array for PATH, `compinit` for completions.
## Reference Loading Table
| Signal | Load These Files | Why |
|---|---|---|
| migrations, bash syntax, POSIX shell | `zsh-bash-migration.md` | Bash→Zsh syntax translation table with code blocks for each pattern |
| parameter expansion, scoping, special vars, fpath | `zsh-quick-reference.md` | Variable flags, expansion flags `${(f)}` `${(s)}` `${(j)}`, special variables |
| implementation patterns, failure modes, detection commands | `zsh-preferred-patterns.md` | Pattern catalog with grep detection and error-fix mappings |
| Go, Rust, Node, Python, starship, direnv, fzf, zoxide, mise | `zsh-tool-integrations.md` | Concrete zsh integration patterns for common dev tools |
## Step 1: Confirm Zsh Context
Before writing any shell code, confirm the target is Zsh:
- `$SHELL` contains `zsh`, or
- Target file has `.zsh` extension, or
- Target file is one of: `.zshrc`, `.zshenv`, `.zprofile`, `.zlogin`, `.zlogout`
If none hold, this skill does not apply — load fish-shell-config.md instead, or stop for bash.
## Step 2: Choose the Correct RC File
Zsh sources startup files in a defined order depending on shell type (login vs. interactive).
**Load order**:
| File | Sourced when | Use for |
|------|-------------|---------|
| `~/.zshenv` | Every zsh invocation (login, interactive, script) | `$PATH`, `$EDITOR`, `$LANG` — variables needed by all processes |
| `~/.zprofile` | Login shells only (before `.zshrc`) | Login-time setup (e.g., `eval "$(brew shellenv)"`) |
| `~/.zshrc` | Interactive shells only | Aliases, functions, completions, prompt, key bindings |
| `~/.zlogin` | Login shells (after `.zshrc`) | Rarely used; message-of-the-day type hooks |
| `~/.zlogout` | Login shell exit | Cleanup on logout |
**Decision tree**:
| What you're writing | Where it goes |
|---------------------|---------------|
| `PATH`, `EDITOR`, `LANG`, `GOPATH` | `~/.zshenv` |
| Homebrew / nix / login-time init | `~/.zprofile` |
| Aliases, functions, `compinit`, prompt | `~/.zshrc` |
| Key bindings (`bindkey`) | `~/.zshrc` |
| `setopt` / `unsetopt` | `~/.zshrc` |
| Framework (oh-my-zsh, prezto) | `~/.zshrc` |
Place env vars in `~/.zshenv` not `~/.zshrc` — scripts and non-interactive shells source `.zshenv` only, so exported variables must live there to reach child processes started from scripts.
## Step 3: Manage PATH
Zsh uses `path` as an array tied to `$PATH`. Use `typeset -U path` to deduplicate automatically.
```zsh
# ~/.zshenv — PATH management
typeset -U path # Enforce unique entries; run once at top of file
path=(
~/bin
~/.local/bin
$path # Preserve existing entries
)
export PATH # Re-export after array modification
```
**fpath and autoload**:
```zsh
# Add completion directories to fpath before compinit
typeset -U fpath
fpath=(~/.zsh/completions $fpath)
# Autoload functions from fpath
autoload -Uz compinit # -U: no alias expansion; -z: zsh-style autoload
autoload -Uz add-zsh-hook
autoload -Uz vcs_info
# Completion cache: only re-init once per day
if [[ -n ~/.zcompdump(#qN.mh+24) ]]; then
compinit
else
compinit -C # -C: skip security check, use cached dump
fi
```
`~/.zcompdump` caches completion definitions. Without the age guard, `compinit` rescans all fpath entries on every shell start — adds 100–300ms of startup time.
## Step 4: Write Variables and Functions
**Variable scoping**:
```zsh
local var="value" # Local to current function
typeset -i count=0 # Integer
typeset -l lower="VALUE" # Auto-lowercased
typeset -u upper="value" # Auto-uppercased
typeset -r CONST="fixed" # Read-only
typeset -x EXPORTED="val" # Export (same as export)
typeset -a arr # Indexed array
typeset -A assoc # Associative array
```
**Functions**:
```zsh
# Regular function
mkcd() {
mkdir -p "$1" && cd "$1"
}
# Alternative (preferred in zsh): function keyword
function mkcd {
mkdir -p "$1" && cd "$1"
}
# Autoloaded function (place in a fpath directory as a standalone file)
# ~/.zsh/functions/mkcd — file contains only the function body:
# mkdir -p "$1" && cd "$1"
# Then in .zshrc: autoload -Uz mkcd
```
For autoloaded functions, the file must be named exactly after the function and live in a `fpath` directory.
## Step 5: Completions
```zsh
# ~/.zshrc — completions setup
# 1. Extend fpath before compinit
fpath=(~/.zsh/completions $fpath)
# 2. Initialize (with cache guard)
autoload -Uz compinit
compinit
# 3. Key completion options
setopt COMPLETE_IN_WORD # Complete from both ends of word
setopt ALWAYS_TO_END # Move cursor to end after completion
setopt AUTO_MENU # Show menu on second Tab
setopt MENU_COMPLETE # Auto-select first match
zstyle ':completion:*' menu select
# 4. Styling completions
zstyle ':completion:*' matcher-list 'm:{a-z}={A-Z}' # Case-insensitive
zstyle ':completion:*' list-colors "${(s.:.)LS_COLORS}"
zstyle ':completion:*:descriptions' format '%B%d%b'
zstyle ':completion:*:warnings' format 'No matches for: %d'
# 5. Add a completion function for a custom command
# ~/.zsh/completions/_mycommand
# #compdef mycommand
# _mycommand() {
# local -a commands
# commands=('start:Start the service' 'stop:Stop the service')
# _describe 'commands' commands
# }
```
## Step 6: Framework Awareness
Detect active framework before adding configuration — frameworks own the prompt, completion init, and plugin loading.
**Detection patterns**:
```zsh
# oh-my-zsh
[[ -n "$ZSH" ]] && echo "oh-my-zsh active (ZSH=$ZSH)"
[[ -f ~/.oh-my-zsh/oh-my-zsh.sh ]] && echo "oh-my-zsh installed"
# prezto
[[ -d ~/.zprezto ]] && echo "prezto installed"
# zinit
[[ -d ~/.zinit ]] || [[ -d ~/.local/share/zinit ]] && echo "zinit installed"
# antigen
command -v antigen &>/dev/null && echo "antigen active"
# powerlevel10k / p10k
[[ -f ~/.p10k.zsh ]] && echo "p10k config present"
```
**Framework coexistence rules**:
| Situation | Action |
|-----------|--------|
| oh-my-zsh active | Place custom config in `~/.oh-my-zsh/custom/` — not directly in `.zshrc` |
| prezto active | Use `~/.zpreztorc` modules; add extra config after `source ~/.zprezto/init.zsh` |
| zinit active | Add plugins with `zinit light`; place after zinit bootstrap block |
| p10k active | Call `[[ -f ~/.p10k.zsh ]] && source ~/.p10k.zsh` after framework init |
| No framework | Full control — structure `.zshrc` with `compinit`, prompt, plugins manually |
When a framework manages `compinit`, do not call `compinit` again — double-init causes duplicate completion definitions and slows startup.
## Step 7: Hooks
Zsh hooks fire at defined shell events. Use `add-zsh-hook` to attach — it preserves existing handlers for the same event.
```zsh
autoload -Uz add-zsh-hook
# precmd: runs before each prompt (use for vcs_info, title updates)
_my_precmd() {
print -Pn "\e]0;%~\a" # Set terminal title to current dir
}
add-zsh-hook precmd _my_precmd
# preexec: runs before each command (receives command string as $1)
_my_preexec() {
print -Pn "\e]0;$1\a" # Set terminal title to running command
}
add-zsh-hook preexec _my_preexec
# chpwd: runs when directory changes
_my_chpwd() {
ls --color=auto # Auto-list on cd
}
add-zsh-hook chpwd _my_chpwd
# zshaddhistory: runs before adding command to history; return 1 to suppress
_no_history() {
[[ "$1" == " "* ]] && return 1 # Leading space = skip history
return 0
}
add-zsh-hook zshaddhistory _no_history
```
Writing `precmd() { ... }` directly overwrites any previously defined `precmd` — `add-zsh-hook` appends to the hook array instead.
## Step 8: Zsh Options
```zsh
# History
setopt HIST_IGNORE_DUPS # Ignore consecutive duplicates
setopt HIST_IGNORE_SPACE # Ignore commands starting with space
setopt HIST_EXPIRE_DUPS_FIRST # Expire duplicates first when trimming
setopt HIST_FIND_NO_DUPS # No dups in history search
setopt SHARE_HISTORY # Share history across sessions
setopt APPEND_HISTORY # Append rather than overwrite
setopt INC_APPEND_HISTORY # Write immediately, not on exit
HISTFILE=~/.zsh_history
HISTSIZE=50000
SAVEHIST=50000
# Globbing
setopt EXTENDED_GLOB # Enable (#q...) glob qualifiers and ^ ~
setopt NULL_GLOB # No-match globs expand to empty (no error)
setopt GLOB_DOTS # Dot files matched by * patterns
# Behavior
setopt PIPE_FAIL # Pipeline exit code = first failed command
setopt NO_CLOBBER # Prevent > from overwriting files
setopt AUTO_CD # cd by typing directory name alone
setopt CORRECT # Suggest corrections for mistyped commands
setopt NO_BEEP # Silence
# Key options to unset
unsetopt BG_NICE # Background jobs run at normal priority
unsetopt FLOW_CONTROL # Disable Ctrl+S/Ctrl+Q flow control
```
**Critical options**:
| Option | Effect | Recommend |
|--------|--------|-----------|
| `PIPE_FAIL` | Pipeline returns exit code of first failed command | Always set |
| `NULL_GLOB` | Unmatched globs expand to empty list | Set to avoid "no matches" errors |
| `EXTENDED_GLOB` | Enables `^`, `~`, `(#q...)` qualifiers | Set when using glob qualifiers |
| `HIST_IGNORE_SPACE` | Commands prefixed with space skip history | Set for sensitive commands |
| `SHARE_HISTORY` | Multiple sessions share history in real time | Set for multi-terminal workflows |
## Step 9: Verify
```zsh
# 1. Syntax check without sourcing
zsh -n ~/.zshrc
# 2. Run in isolated environment (no user config)
zsh --no-rcs -c 'source ~/.zshrc; echo ok'
# 3. Profile startup time
time zsh -i -c exit
# 4. Trace file loading order
zsh --sourcetrace -i -c exit 2>&1 | head
# 5. Profile compinit specifically
zsh -i -c 'zmodload zsh/zprof; compinit; zprof' 2>&1 | head -20
```
**Glob quoting pitfalls**: With `EXTENDED_GLOB` set, `^`, `~`, and `#` are active in unquoted contexts. Quote them in strings: `echo "it's ~fine"` passes literally; `echo it's ~fine` expands `~fine` as a path.
**NULL_GLOB vs no-match error**: Without `NULL_GLOB`, `rm *.tmp` fails with "no matches" when no `.tmp` files exist. With `NULL_GLOB`, `rm *.tmp` expands to `rm` with no arguments (also an error). Use glob qualifier `(N)` for conditional expansion: `rm -- *.tmp(N)` silently does nothing when there are no matches.
## References
| Task Signal | Load | Why |
|-------------|------|-----|
| Migrating from Bash, converting `.bashrc`, `export VAR=`, `[[ ]]`, arrays, heredocs | `zsh-bash-migration.md` | Full Bash→Zsh syntax translation table |
| Variable scoping, `typeset` flags, `${(f)}` `${(s:,:)}` expansion, `$REPLY`, `$MATCH` | `zsh-quick-reference.md` | Parameter expansion flags, special variables, control flow cheatsheet |
| Error audit, PATH not persisting, completions slow, glob errors, hook not firing | `zsh-preferred-patterns.md` | Failure modes with grep detection commands and error-fix mappings |
| Go, Rust, Docker, Node.js, Python, pyenv, fnm, starship, direnv, fzf, zoxide, mise | `zsh-tool-integrations.md` | Concrete integration patterns for common dev tools |
- `${CLAUDE_SKILL_DIR}/references/zsh-bash-migration.md`: Complete Bash-to-Zsh syntax translation table
- `${CLAUDE_SKILL_DIR}/references/zsh-quick-reference.md`: Variable scoping, parameter expansion flags, and special variables
- `${CLAUDE_SKILL_DIR}/references/zsh-preferred-patterns.md`: Failure mode catalog with grep detection commands and error-fix mappings
- `${CLAUDE_SKILL_DIR}/references/zsh-tool-integrations.md`: Concrete integration patterns for Go, Rust, Docker, Node.js, Python, and shell enhancers
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |