agentsclimarketplace

Triage dotfiles env

Skill urmzd/dotfiles/dot_agents/skills/triage-dotfiles-env

Cross-platform dotfiles managed by Chezmoi with Homebrew/apt and per-language version managers. One-command bootstrap for macOS and Linux with Neovim, Tmux, Zsh, and AI agent skills.

Install
npx -y skills add urmzd/dotfiles --skill triage-dotfiles-env

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Playbook of known failure modes in this dotfiles stack: pipx "bad interpreter" after Python rebuilds, gpg commit-signing failures, direnv/nix shellHook running bash instead of zsh, Powerlevel10k instant-prompt warnings, and Neovim plugin errors from removed Lua APIs. Use when a shell startup error, git signing failure, broken CLI shim, or nvim stack trace appears on this machine. Do NOT use for generic runtime debugging in projects (use diagnose-runtime), chezmoi naming and templating conventions (use dotfiles), or authoring pinned installers (use setup-devenv-with-chezmoi).

SKILL.md

4.2 KB, 927 tokens by cl100k_base, as published. Nobody here has run it

Triage Dotfiles Environment

Look the symptom up here before debugging from scratch. Every fix ends with its verification step; a fix without verification is not done.

Known failure modes

pipx shims: "bad interpreter: no such file or directory"

Seen repeatedly in .zshrc completions (register-python-argcomplete: bad interpreter).

  • Cause: a Homebrew or uv Python upgrade rebuilt the interpreter path; every pipx venv shebang now points at a deleted Python.
  • Fix: pipx reinstall-all. If pipx itself is broken: brew reinstall pipx && pipx reinstall-all.
  • Verify: open a fresh zsh -l and confirm zero startup errors, then run the failing shim directly.

gpg: "cannot run gpg: No such file or directory" on commit

  • Cause: git config points at a gpg binary that moved (brew relink, new machine), or GPG_TTY is unset in a non-login context.
  • Fix: git config --global gpg.program "$(command -v gpg)", ensure the zshrc exports GPG_TTY=$(tty), and confirm user.signingkey matches gpg --list-secret-keys --keyid-format long.
  • Verify: git commit --allow-empty -m "test: signing" && git log --show-signature -1, then drop the test commit.

direnv + nix: shellHook runs bash, not zsh

Symptoms: aliases and functions missing inside a nix shell, prompts wrong, zsh-only syntax errors from hooks.

  • Cause: nix shellHook always executes in bash. zsh config never runs.
  • Fix: keep shellHook to environment exports only; put interactive setup in zsh init guarded by IN_NIX_SHELL. Never source zsh files from shellHook.
  • Verify: direnv exec . zsh -ic 'echo $SHELL; alias | head'.

Powerlevel10k instant-prompt warnings

  • Cause: something in .zshrc prints output before the instant-prompt block (installer scripts, completion generators, version managers).
  • Fix: move the offending line below the instant-prompt block or silence its output; keep the instant-prompt block first.
  • Verify: fresh zsh -l shows no warning banner.

Neovim: plugin errors from removed Lua APIs

Example: E5108 ... attempt to call field 'buf_get_clients' (a nil value) (API removed; modern equivalent vim.lsp.get_clients).

  • Cause: plugin pinned by lazy.nvim lockfile predates a Neovim HEAD API removal, or an abandoned plugin needs replacement.
  • Fix: :Lazy update the plugin first; if abandoned, patch the call or swap the plugin. Check ~/.local/state/nvim/log for the full trace.
  • Verify: nvim --headless "+lua print('ok')" +q exits clean, then open a file that previously triggered the error. A pasted-twice error means the first fix was never verified; always run this step.

Completions stale after adding or removing CLIs

  • Cause: generated completions in the chezmoi-managed dir lag the installed tool set.
  • Fix: re-run the completion generation script via chezmoi apply (it is an run_onchange script keyed to the Brewfile and zshrc).
  • Verify: zsh -ic 'compdef | grep <tool>'.

Method for anything not listed

  1. Reproduce in a fresh shell (zsh -l or zsh -ic '<cmd>'), never only in the current polluted session.
  2. Bisect the init chain: zsh -df (clean), then add zshrc, then direnv, then nix. The first layer that reproduces owns the bug.
  3. Fix in the chezmoi source (chezmoi edit), apply, and re-verify from a fresh shell.
  4. Add the new failure mode to this skill so it is a lookup next time.

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.