mcpField
C
configuring-zsh

configuring-zsh

github.com/bostonaholicDevelopment268 installsUpdated today
Repository

About configuring-zsh

A skill for editing and validating zsh startup configuration in dotfiles. It guides developers through file placement, symlink handling, alias safety, and shell-specific checks.

Key features

  1. 01Choosing the correct startup file
  2. 02Editing dotfile sources, not symlinks
  3. 03Checking aliases for conflicts
  4. 04Validating syntax and shell behavior

Use cases

  1. 01Adding variables, options, or plugins to zsh
  2. 02Preventing aliases from disrupting scripts or agents
  3. 03Testing changes to startup files

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/bostonaholic/skills --skill configuring-zsh

After installing, type/configuring-zshin Claude Code to confirm it loaded.

Bundled filesagents/openai.yamlreferences/oh-my-zsh-plugin-layout.md

Details

From the project README

Configuring zsh

Edit the source, not the symlink

  • Startup files usually live in a dotfiles repo and are symlinked into $HOME (or $ZDOTDIR).
  • Write to the repo file, not the link: many editors and write tools replace a symlink with a regular file.
  • Register a new startup file wherever the repo creates its links, and ask before running its installer.
  • If the repo links a <name>.plugin.zsh into ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/<name>/, follow the oh-my-zsh plugin layout.

Choose the startup file

  • .zprofile: PATH, tool init that sets it (eval "$(brew shellenv)"), variables for programs (EDITOR). Not .zshenv: macOS path_helper moves its entries behind the system paths. Not .zshrc: it never runs for programs started outside an interactive shell.
  • .zshenv: variables every shell needs, including scripts (ZDOTDIR, guard flags). Keep it fast and silent.
  • .zshrc: setopt, zstyle, prompt, framework and plugin list; FPATH additions before compinit (with oh-my-zsh, before sourcing oh-my-zsh.sh); aliases, functions, their compdef, and interactive variables (LESS) after compinit, or in the custom plugin file.

Before adding an alias or function, check that an enabled plugin does not already define it: zsh -ic 'whence -v <name>'.

Aliases that shadow commands

  • An alias that replaces a standard command (ls, cat, grep, rm, cd) breaks scripts and agents that shell out through this config.
  • Agent harnesses may replay aliases captured from an interactive shell, so an interactivity check alone does not protect them.
  • If the config already has a guard for shadowing aliases, put the new alias behind it.
  • Otherwise ask the user before adding one, and suggest a guard that also checks agent markers such as CLAUDECODE.
  • Aliases with new names (lg, gti) need no guard.

Validate

  1. zsh -n <file> for each edited file.
  2. Confirm the change with zsh -c for .zshenv, zsh -lc for .zprofile, zsh -ic for .zshrc or a plugin.
  3. For a guarded alias, read every marker the guard tests, then confirm the definition prints with all of them unset (env -u CLAUDECODE -u AI_AGENT zsh -ic 'alias <name>', one -u per marker) and is gone with one set (CLAUDECODE=1 zsh -ic 'alias <name>').

Comments

Markdown supported