AgentSkillsCN

configuring-zsh

配置并排查 Zsh Shell。当您需要编辑 .zshenv、.zprofile、.zshrc、.zlogin 或 .zlogout，设置 powerlevel10k 提示符，配置 oh-my-zsh 或 Sheldon 插件管理器，修复 PATH 或环境变量，调试 Shell 启动缓慢的问题，设置补全/compinit/fpath，或使用 zsh-autocomplete、zsh-autosuggestions 或 zsh-syntax-highlighting 插件时，可使用此技能。

SKILL.md
--- frontmatter
name: configuring-zsh
description: 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.

Zsh Shell Configuration

Quick Reference

TopicReference
Startup file orderstartup-files.md
oh-my-zsh patternsoh-my-zsh.md
powerlevel10k setuppowerlevel10k.md
sheldon plugin managersheldon.md
Plugin load orderplugins.md
Performance tuningperformance.md

Workflow Decision Tree

Need to...Action
Set env vars / PATH / localesRead startup-files.md → edit .zshenv or .zprofile
Configure aliases, keybinds, completions, promptEdit .zshrc
Fix performance issuesRead performance.md → profile startup
Add/configure pluginsRead 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

TaskApproach
Add env var.zshenv (everywhere) vs .zprofile (login) vs .zshrc (interactive)
Fix PATHEnsure ordering, remove duplicates, avoid PATH=$PATH:... in multiple files
Enable completionsSet fpath → compinit once → cache if needed
Add pluginChoose manager → ensure correct load order
Setup p10kInstant prompt block first in .zshrc → source ~/.p10k.zsh after plugins