configuring-zsh

Original：🇺🇸 English

Translated

Configure and troubleshoot Zsh shell. Use when editing .zshenv, .zprofile, .zshrc, .zlogin, or .zlogout, setting up powerlevel10k prompt, configuring oh-my-zsh or sheldon plugin manager, fixing PATH or environment variables, debugging slow shell startup, setting up completions/compinit/fpath, or working with zsh-autocomplete, zsh-autosuggestions, or zsh-syntax-highlighting plugins.

4installs

Sourcemrpointer/dotfiles

Added on2026-11-04

NPX Install

npx skill4agent add mrpointer/dotfiles configuring-zsh

SKILL.md Content

View Translation Comparison →

Zsh Shell Configuration

Quick Reference

Topic	Reference
Startup file order	startup-files.md
oh-my-zsh patterns	oh-my-zsh.md
powerlevel10k setup	powerlevel10k.md
sheldon plugin manager	sheldon.md
Plugin load order	plugins.md
Performance tuning	performance.md

Workflow Decision Tree

Need to...	Action
Set env vars / PATH / locales	Read `startup-files.md` → edit `.zshenv` or `.zprofile`
Configure aliases, keybinds, completions, prompt	Edit `.zshrc`
Fix performance issues	Read `performance.md` → profile startup
Add/configure plugins	Read `plugins.md` + relevant manager reference

Chezmoi Integration

Edit Zsh configs in the chezmoi source (this repo), not directly in
```
~
```
Respect
```
{{ ... }}
```
template blocks in files

Source naming:

dot_zshrc

→

~/.zshrc

,

private_dot_config/sheldon

→

~/.config/sheldon

For chezmoi workflows, see
```
managing-chezmoi
```
skill

Default Guardrails

Keep
```
.zshenv
```
idempotent and fast; no external commands
No aliases/functions in
```
.zshenv
```
Use
```
typeset -gx VAR=...
```
or
```
export VAR=...
```
with defensive checks
Set
```
fpath
```
before
```
compinit
```
; run
```
compinit
```
once only
Document plugin load order (especially
```
zsh-autocomplete
```
+
```
zsh-syntax-highlighting
```
)

Common Tasks

Task	Approach
Add env var	`.zshenv` (everywhere) vs `.zprofile` (login) vs `.zshrc` (interactive)
Fix PATH	Ensure ordering, remove duplicates, avoid `PATH=$PATH:...` in multiple files
Enable completions	Set `fpath` → `compinit` once → cache if needed
Add plugin	Choose manager → ensure correct load order
Setup p10k	Instant prompt block first in `.zshrc` → source `~/.p10k.zsh` after plugins