Dotfiles Config Skill

Golden Rule

ALWAYS edit files in ~/dev/dotfiles/, NEVER edit symlinked files in ~/ or ~/.config/.

The files in your home directory are symlinks pointing back to this repo. Verify with:

ls -la ~/.config/ghostty/config  # Should show symlink to dotfiles

Repository Structure

~/dev/dotfiles/
├── home/                    # Base configs (all platforms)
│   ├── .claude/             # Claude Code config (this skill lives here)
│   ├── .config/             # XDG configs
│   │   ├── alacritty/
│   │   ├── ghostty/
│   │   ├── helix/
│   │   ├── home-manager/    # Nix Home Manager (CLI tools)
│   │   ├── lazygit/
│   │   ├── nvim/
│   │   ├── yazi/
│   │   ├── zellij/
│   │   └── zsh/
│   ├── .bashrc
│   ├── .tmux.conf
│   └── .zshrc
├── home-mac/                # macOS-specific configs
│   └── Brewfile             # GUI apps via Homebrew
├── home-linux/              # Linux-specific configs
├── mac/
│   └── nix-darwin/          # macOS system settings
└── ubuntu/                  # Ubuntu-specific configs

Config File Locations

Tool	Dotfiles Location	Symlinked To
Alacritty	`home/.config/alacritty/`	`~/.config/alacritty/`
Claude Code	`home/.claude/`	`~/.claude/`
Ghostty	`home/.config/ghostty/`	`~/.config/ghostty/`
Helix	`home/.config/helix/`	`~/.config/helix/`
Home Manager	`home/.config/home-manager/`	`~/.config/home-manager/`
Lazygit	`home/.config/lazygit/`	`~/.config/lazygit/`
Neovim	`home/.config/nvim/`	`~/.config/nvim/`
Ripgrep	`home/.config/rg/`	`~/.config/rg/`
Starship	`home/.config/starship.toml`	`~/.config/starship.toml`
Tmux	`home/.tmux.conf`	`~/.tmux.conf`
Yazi	`home/.config/yazi/`	`~/.config/yazi/`
Zellij	`home/.config/zellij/`	`~/.config/zellij/`
Zsh	`home/.zshrc`, `home/.config/zsh/`	`~/.zshrc`, `~/.config/zsh/`

Package Management

CLI Tools (Nix Home Manager)

Edit: home/.config/home-manager/home.nix Apply: home-manager switch

GUI Apps (macOS Homebrew)

Edit: home-mac/Brewfile Apply: cd home-mac && brew bundle

Language Runtimes (mise)

Edit: home/.config/mise/config.toml Apply: mise install

macOS System Settings (nix-darwin)

Edit: mac/nix-darwin/flake.nix Apply: just nix-darwin-switch

Stow Commands

After adding new config files, re-run stow:

just stow-mac    # macOS
just stow-linux  # Linux
just stow-home   # Just base home/

Skills Location

Skills live in home/.claude/skills/ and are symlinked to ~/.claude/skills/.

To create a new skill:

Create directory: mkdir -p home/.claude/skills/skill-name
Create SKILL.md with frontmatter (name, description)
Stow will automatically symlink it

Common Mistakes to Avoid

Editing symlinked files - Always navigate to ~/dev/dotfiles/ first
Forgetting to stow - New files need just stow-* to create symlinks
Wrong platform directory - macOS GUI apps go in home-mac/, not home/
Editing ~/.config directly - These are symlinks, edit the source in dotfiles

Verification

Before declaring a config change complete:

Confirm you edited the file in ~/dev/dotfiles/
Check the symlink exists: ls -la ~/.config/<tool>/
Test the config works (reload app or run verification command)

dotfiles-config