skilld
All skills
simota avatar

/hearth

@16a3f28
by shingo imotasimota/agent-skills85 stars
15

Generating and auditing personal dev environment configs (zsh/tmux/neovim/ghostty) and automating the macOS desktop via AppleScript/JXA (Finder, Mail, Safari). Use for dotfiles or Apple Events.

Ask your Agent

Use this Skill: https://skilld.dev/gh/simota/agent-skills/hearth

This session only. Nothing lands on disk.

referenceshell-config-anti-patterns.md

≈1.3k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Shell Configuration Anti-Patterns

Purpose: Read this when auditing shell startup performance, module structure, plugin-management risk, or shell regressions. Keep the SH-* and PM-* identifiers intact in findings and handoffs.

Contents

Startup-Performance Anti-Patterns

Code Anti-pattern Risk Signal Countermeasure
SH-01 Eager version-manager loading nvm / pyenv / rbenv / conda add 300-500ms each Shell startup exceeds 1s Lazy-load wrappers or consolidate with mise
SH-02 Multiple compinit calls Completion initialization repeats 200ms+ work Completion setup appears in multiple files Run compinit once after $fpath is complete and cache the dump daily
SH-03 Full oh-my-zsh framework usage Framework + completion dominate startup cost Framework time dominates zprof Keep only required plugins or switch to sheldon / zim
SH-04 Synchronous plugin loading Startup cost grows linearly with plugin count Prompt appears only after all plugins load Use zsh-defer, sheldon defer, or zinit turbo
SH-05 Heavy prompt rendering Prompt runs expensive subprocesses on every draw Large repos make the prompt stall Prefer starship or powerlevel10k instant prompt
SH-06 eval "$(tool init zsh)" everywhere Re-runs tool initialization on every shell start starship, zoxide, or fzf init calls dominate profiles Cache the generated init script and source the cache
SH-07 Auto-update on every launch Hidden network checks slow every shell start Plugin manager checks the network at startup Disable auto-update and update explicitly

Structure Anti-Patterns

Pattern Risk Countermeasure
Monolithic .zshrc Change impact is unclear; debugging is slow Split into env.zsh, aliases.zsh, plugins.zsh, local.zsh, and related modules
No local.zsh separation Machine-specific values leak into tracked files Keep machine-local data in a gitignored file
Hard-coded paths Shared configs break across macOS and Linux Detect OS and tool installation paths before exporting them
No XDG compliance Home directory sprawl and weak portability Set ZDOTDIR=$XDG_CONFIG_HOME/zsh in ~/.zshenv
Source-order mistakes Tools fail because PATH or env vars are not ready Preserve env -> path -> plugins -> completions -> aliases -> local

Plugin-Management Anti-Patterns

Code Anti-pattern Risk Countermeasure
PM-01 Plugin hoarding Unused plugins keep slowing startup Review monthly and remove plugins unused for two weeks
PM-02 Framework lock-in Adding or swapping plugins becomes expensive Prefer per-plugin managers such as sheldon or zim
PM-03 Compilation overhead Compile steps add first-run latency and cache issues Prefer sheldon when compile-time tricks are unnecessary
PM-04 No plugin pinning Updates break reproducibility Pin tags or commit SHAs where the manager supports it

Measurement and Targets

Measurement Commands

Profiling:
  1. zmodload zsh/zprof
  2. zprof

Wall-clock:
  /usr/bin/time zsh -i -c exit
  hyperfine 'zsh -i -c exit'

Startup Targets

Profile Target Upper bound
Minimal < 50ms < 100ms
Standard < 150ms < 250ms
Power < 250ms < 400ms

Optimization Priority

  1. Lazy-load version managers: expected improvement 300-500ms
  2. Run compinit once and cache results: expected improvement 100-200ms
  3. Remove unused plugins: expected improvement 50-150ms
  4. Simplify the prompt: expected improvement 50-100ms
  5. Cache tool init output: expected improvement 30-80ms

Quality Gates

  • Startup time > 250ms requires zprof analysis and a bottleneck report.
  • .zshrc over 200 lines should trigger modularization guidance.
  • .zshrc over 500 lines is an anti-pattern, not just a style issue.
  • Keep compinit to one call after $fpath is final.

How Hearth Uses This Reference

SCAN:
  Screen for SH-01..07 startup regressions

PLAN:
  Check module structure, XDG layout, and plugin strategy

CRAFT:
  Design fixes for PM-01..04 and source-order issues

VERIFY:
  Run timing, profiling, and target comparison

Required Gates

  • Detect eval "$(tool init)" and recommend cache-based replacement.
  • Detect full oh-my-zsh usage and recommend lighter alternatives.
  • Detect direct nvm / pyenv eager loading and recommend lazy loading or mise.
  • Detect non-XDG zsh layouts and recommend ZDOTDIR migration.

Source: SKILL.md on GitHub

Third-party checks

2 warnings5mo5 checks · Risk SAFE
  • Gen Agent Trust Hub5mo

    Hearth is a personal environment management skill designed to configure and optimize developer dotfiles for shells, terminals, and editors. It emphasizes security best practices, including secret detection with Gitleaks and adherence to XDG Base Directory standards. The skill utilizes industry-standard tools and fetches dependencies from trusted or well-known open-source repositories.

  • Socket5mo

    No alerts

  • Snyk5mo

    Risk: MEDIUM · 2 issues

  • Runlayer6mo

    4/10 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 16a3f28. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 days ago.

Activeupdated last month

README badge

README badge for simota/agent-skills/hearth