Zsh Expert
Give your coding agent a Zsh-native mental model for scripts, startup files, completions, ZLE widgets, prompts, plugins, framework integrations, and asynchronous interactive code.
A skill, not a shell plugin: install it for your agent to read. Do not source it from .zshrc.
First stable release: v1.0.0 follows successful use in two real-world projects and carries its version in both the skill metadata and a matching Git tag.
Zsh Is Not Bash with Extra Features
Advice written for Bash or portable sh is often subtly wrong in native Zsh. Zsh Expert starts by identifying the execution context, version, framework, trust boundaries, and user-visible latency—then applies the semantics that actually govern that environment.
Correct Expansion
Model lists as arrays, preserve element boundaries, and explain multi-stage expansion instead of hiding it in punctuation.
Scoped Behavior
Use native function scope and localized options without leaking surprising state back into the caller's shell.
Interactive Reality
Treat completions, ZLE, prompts, terminals, hooks, workers, and redraws as stateful systems—not ordinary batch scripts.
24 FOCUSED REFERENCES • 4 PRACTICAL AREAS
The Whole Zsh Surface, Routed by Task
The core skill stays concise and loads only the chapters a task needs. Cross-cutting work automatically brings security and testing guidance into the same review.
Language and data
Execution order, parameters, arrays, expansion flags, patterns, glob qualifiers, and native data boundaries.
Reusable programs
Functions, dynamic scope, option hygiene, traps, redirections, input parsing, native modules, jobs, and async work.
Interactive systems
Startup files, compsys, completion authoring, ZLE, prompts, VCS state, hooks, and plugin and framework lifecycles.
Quality and boundaries
Performance, security, testing, debugging, profiling, Bash migration, version gates, and research provenance.
Depth Without Loading a Shell Manual Every Time
Progressive disclosure keeps routine fixes lean while preserving specialist material for expansion algebra, completion authoring, async callbacks, security, profiling, portability, and version gates.
zsh-expert/
├── SKILL.md # Contract, invariants, and routing
├── references/ # 24 focused engineering chapters
├── scripts/verify-zsh.zsh # Parse and opt-in smoke tests
├── agents/openai.yaml # Codex display metadata
└── README.md # Installation and usageSafe to Add to an Existing Shell
Preserve the caller
Reusable code keeps aliases, options, traps, keymaps, hooks, prompts, and file descriptors intact unless ownership is explicit.
Compose with the ecosystem
Hook arrays, completion security, and plugin lifecycle rules prevent one customization from silently replacing another.
Treat text as a boundary
Evaluation, pattern compilation, prompt substitution, completion output, terminal input, and directory-local files receive explicit trust handling.
Gate version-sensitive behavior
Stable Zsh behavior stays separate from post-release development, with newer features checked against the declared minimum version.
A Bash Linter Is Not a Zsh Oracle
The bundled verifier parses files with isolated Zsh by default. Its opt-in smoke mode executes trusted non-interactive code under zsh -df with a temporary ZDOTDIR. Completion, ZLE, prompt, signal, and job-control behavior still gets a pseudo-terminal test with observable assertions.
# Parse without loading user startup files
scripts/verify-zsh.zsh path/to/file.zsh
# Execute only code you trust to run non-interactively
scripts/verify-zsh.zsh --smoke path/to/safe-script.zshOne Command—or an Explicit Location
Install the named skill directly from GitHub with the skills CLI. Prefer to control its location yourself? Keep a personal clone for every repository, or add it as a submodule when the guidance should travel with one project.
Install with the skills CLI
View on skills.sh ↗npx skills add https://github.com/zaguanlabs/zsh-expert-skill --skill zsh-expertPersonal
mkdir -p "$HOME/.agents/skills"
git clone \
https://github.com/ZaguanLabs/zsh-expert-skill.git \
"$HOME/.agents/skills/zsh-expert"Repository-scoped
mkdir -p .agents/skills
git submodule add \
https://github.com/ZaguanLabs/zsh-expert-skill.git \
.agents/skills/zsh-expertRestart Codex if the skill does not appear immediately after a manual installation.
Ask for the Work You Actually Need
$zsh-expert Review this plugin for option leakage and hook conflicts.$zsh-expert Write a stateful completion function for this CLI.$zsh-expert Diagnose why this async ZLE widget redraws stale output.$zsh-expert Port this Bash script to idiomatic native Zsh 5.9.Research You Can Trace
The source map pins stable Zsh semantics and tests, separates post-release development, and records the implementations behind interactive patterns. Oh My Zsh is a major source of inspiration and a valuable research corpus—not a dependency or the skill's primary target. Its lessons are generalized into native Zsh guidance and checked against upstream semantics.