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

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:

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

Common Mistakes to Avoid

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

Verification

Before declaring a config change complete:

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