🎯

zsh

🎯Skill
g1joshi/agent-skills1 Installs9Last Updated Feb 10, 2026

Installation

$npx skills add g1joshi/agent-skills --skill zsh

Run it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).

Uses skills.sh Β· Node.js 22.20+

After installing

Ask for related work and the agent uses it on its own, or call it yourself.

Run it (Claude Code)/zsh
Install by hand

Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.

Open the skill folder β†’
  • This project .claude/skills/zsh/
  • All projects ~/.claude/skills/zsh/

These paths are for Claude Code. For other tools, the command above puts it in the right place.

Expert Zsh assistance covering shell customization, Oh My Zsh plugins, Zinit plugin manager, prompt engineering (Starship/Powerlevel10k), and shell scripting. Use when configuring .zshrc, writing Zsh automation scripts, optimizing shell startup time, or configuring tab-completion.

Zsh

Zsh is the default shell on macOS. It is highly customizable and compatible with Bash.

When to Use

  • High-Productivity Interactive Shell: Interactive autocompletion, fuzzy navigation, history search, and branch indicators.
  • Modern CLI Plugin Ecosystem: Accelerating shell workflows with zsh-autosuggestions, zsh-syntax-highlighting, and Starship prompt.
  • Robust Shell Scripting: Authoring POSIX-compatible and Zsh-extended automation scripts with array manipulation and globbing.
  • Enterprise Environment Management: Managing SDK versions, PATH exports, and aliases across macOS and Linux servers.

Quick Start

1. Minimal ~/.zshrc Setup

# History configuration
HISTFILE="$HOME/.zsh_history"
HISTSIZE=50000
SAVEHIST=50000
setopt HIST_IGNORE_DUPS
setopt SHARE_HISTORY

# Key bindings (emacs mode)
bindkey -e

# Autocompletion
autoload -Uz compinit && compinit

# Aliases
alias ll="ls -lah"
alias g="git"
alias gs="git status -sb"

2. Benchmark Startup Time

# Profile zsh startup duration
time zsh -i -c exit

Core Concepts

High-Speed Modern Zshrc (~/.zshrc)

Configuring sub-20ms shell startup, smart completion, and history:

# ~/.zshrc
# History configuration
HISTFILE="$HOME/.zsh_history"
HISTSIZE=50000
SAVEHIST=50000
setopt EXTENDED_HISTORY
setopt HIST_EXPIRE_DUPS_FIRST
setopt HIST_IGNORE_DUPS
setopt HIST_IGNORE_SPACE
setopt HIST_VERIFY
setopt SHARE_HISTORY

# Directory navigation options
setopt AUTO_CD
setopt AUTO_PUSHD
setopt PUSHD_IGNORE_DUPS
setopt PUSHD_SILENT

# Fast Completion System (with caching)
autoload -Uz compinit
typeset -i updated_at=$(date +'%j' -r ~/.zcompdump 2>/dev/null || stat -f '%Sm' -t '%j' ~/.zcompdump 2>/dev/null)
if [ $(date +'%j') != $updated_at ]; then
  compinit -i
else
  compinit -C -i
fi

# Modern Keybindings: History search
bindkey -e
bindkey '^[[A' history-search-backward
bindkey '^[[B' history-search-forward

# Initialize Starship Prompt (if installed)
if command -v starship &> /dev/null; then
  eval "$(starship init zsh)"
fi

Lightweight Plugin Loading without Heavy Frameworks

Loading autosuggestions and syntax highlighting directly:

# Clone plugins to ~/.zsh/plugins/
# git clone https://github.com/zsh-users/zsh-autosuggestions ~/.zsh/plugins/zsh-autosuggestions
# git clone https://github.com/zsh-users/zsh-syntax-highlighting ~/.zsh/plugins/zsh-syntax-highlighting

source ~/.zsh/plugins/zsh-autosuggestions/zsh-autosuggestions.zsh
source ~/.zsh/plugins/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh

# Configure suggestion color
ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE='fg=8'

Advanced Zsh Globbing & Parameter Expansion

Leveraging recursive globbing and modifiers:

# List all TypeScript files modified in the last 24 hours
ls -lh **/*.ts(m-1)

# Delete all empty directories recursively
rmdir -p **/*(/^F) 2>/dev/null

# Select only executable files in bin/
chmod +x bin/*(*)

Common Patterns

High-Speed Plugin Loading with Zinit

Problem: Oh My Zsh startup takes hundreds of milliseconds due to heavy eager loading.
Solution: Use Zinit with turbo mode (deferred loading).

# Install Zinit if missing
source ~/.local/share/zinit/zinit.git/zinit.zsh

# Turbo load syntax highlighting and autosuggestions asynchronously
zinit wait lucid for \
  atinit"ZINIT[COMPINIT_OPTS]=-C; zicompinit; zicdreplay" \
    zdharma-continuum/fast-syntax-highlighting \
  atload"_zsh_autosuggest_start" \
    zsh-users/zsh-autosuggestions \
  blockf \
    zsh-users/zsh-completions

Robust Shell Scripting Functions

Problem: Write reusable shell functions with option parsing and error handling.
Solution: Use standard Zsh parameter expansions.

# mkcd: Create directory and cd into it
mkcd() {
  if [[ -z "$1" ]]; then
    echo "Usage: mkcd <dir>" >&2
    return 1
  fi
  mkdir -p "$1" && cd "$1"
}

Best Practices

Do:

  • Compile ~/.zcompdump into a byte-compiled file (compdump.zwc) to accelerate shell startup time.
  • Set setopt SHARE_HISTORY to synchronize command history across all active terminal tabs.
  • Use Starship or a lean native prompt rather than bloated legacy prompt themes.
  • Profile startup latency using zmodload zsh/zprof at top and bottom of ~/.zshrc.

Don't:

  • Use heavy, bloated framework configurations (monolithic Oh-My-Zsh configurations) with dozens of unneeded plugins.
  • Store plaintext cloud credentials, API tokens, or secrets in ~/.zshrc; use private .env files or secret vaults.
  • Run slow external commands (nvm, brew doctor) synchronously on every interactive shell launch.

Troubleshooting

ErrorCauseSolution
zsh: command not found: ... after editing .zshrcSyntax error in .zshrc or $PATH assignment overwritten instead of prependedPrepend paths properly: export PATH="$HOME/bin:$PATH" and run source ~/.zshrc.
zsh compinit: insecure directories, run compauditInsecure file permissions on /usr/local/share/zshRun compaudit | xargs chmod g-w,o-w to fix directory permissions.
Zsh starts very slowly (> 500ms)Synchronous nvm or heavy plugin initializationUse lazy loading for nvm or profile with zmodload zsh/zprof at top of .zshrc and zprof at bottom.

References

More from this repository10